计量

自定义应用度量衡由Amazon Cloud Watch支持(通过嵌入量子格式).

何时使用 : 您需要跟踪随时间推移的数值测量——请求计数,出错率,耐久性,队列深度,商业KPI. 对仪表板,警报器,以及操作能见度都有好处.

不使用时 : 如果需要结构化的日志输出,请使用 Logging。如果需要分布式请求跟踪,则使用 Tracing。如果需要存储用于查询的时间序列数据,则使用 Database 或者说 DistributedTable。 。 。 .

设计与模拟等价细节 : 设计

API 密码

const metrics = new Metrics(scope, id, options?)

选项

释放选项

计量单位

type MetricUnit =
  | 'Count' | 'Seconds' | 'Milliseconds' | 'Microseconds'
  | 'Bytes' | 'Kilobytes' | 'Megabytes' | 'Gigabytes'
  | 'Percent' | 'Bits/Second' | 'None';

处理错误

import { isBlocksError } from '@aws-blocks/core';
import { MetricsErrors } from '@aws-blocks/bb-metrics';

try {
  metrics.emit('', 1);
} catch (e: unknown) {
  if (isBlocksError(e, MetricsErrors.InvalidMetricName)) {
    // metric name is empty or exceeds 1024 characters
  }
}

实例

基本用途

import { Scope, ApiNamespace } from '@aws-blocks/blocks';
import { Metrics } from '@aws-blocks/bb-metrics';

const scope = new Scope('my-app');
const metrics = new Metrics(scope, 'appMetrics', {
  namespace: 'MyApp/Orders',
  defaultDimensions: { service: 'orders' },
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async handleRequest() {
    metrics.emit('RequestCount', 1, { unit: 'Count' });
    metrics.emit('Latency', 42, { unit: 'Milliseconds' });
    return { ok: true };
  },
}));

带有尺寸的释放

metrics.emit('RequestCount', 1, {
  unit: 'Count',
  dimensions: { endpoint: '/api/users', method: 'GET' },
});

批发

metrics.emitBatch([
  { name: 'RequestCount', value: 1, unit: 'Count' },
  { name: 'Latency', value: 42, unit: 'Milliseconds' },
  { name: 'ErrorCount', value: 0, unit: 'Count' },
]);

儿童用品(范围)

const requestMetrics = metrics.child({ endpoint: '/api/users', method: 'GET' });
requestMetrics.emit('RequestCount', 1);
requestMetrics.emit('Latency', 35, { unit: 'Milliseconds' });

孩子们继承了父母的取名空间和默认维度,将自己在顶上合并. 儿童可以任意筑巢.

环绕已存在的命名空间

const legacy = new Metrics(scope, 'legacy', {
  metrics: Metrics.fromExisting('MyOrg/SharedMetrics'),
});
legacy.emit('MigrationCount', 1);

高分辨率度量衡

metrics.emit('CPUSpike', 95.2, {
  unit: 'Percent',
  resolution: 'high', // 1-second aggregation
});

CDK 配置

CDK 构造不创建 AWS 资源 。 它只会解决和暴露 namespace 财务报告和审定财务报表 defaultDimensions 为 CDK-time 消费者只读属性.

EMF使用Cloud Watch日志(Lambda已经对此有权限),因此没有环境变量或 cloudwatch:PutMetricData 需要IAM赠款。 在第一个测量数据点到达时默认创建了CloudWatch命名空间.

同步 API 理由说明

所有计量方法返回 void没有 Promise<void>这是故意的:

• EMF 写入 stdout —— 说 process.stdout.write() 是 Linux 上一个同步的、非屏蔽的呼叫。 内核缓冲出写作,兰布达的伐木代理人同步捕捉.
• 无网络 I/ 欧 - 与众不同 PutMetricData (这让HTTP呼叫Cloud Watch),"云表日志"上的EMF猪背,Lambda已经流出. 没有什么 await。 。 。 .
• 无 ——回归承诺将增加零效益的微任务时间安排。 量子应该像一个便宜的 console.log。 。 。 .
• 火和遗忘的语义 ——计量是可观察性数据,不是商业批判性写作. 如果一个公尺未放出(例如stdout被关闭),它不应该崩溃请求.

这种设计意味着你可以在任何地方——在热回环,同步回调,或错误处理器——发射出度量衡,而不必担心同源上下文或未处理的承诺拒绝.

最佳做法

• 维度基本值保持低(避免用户ID或请求ID作为维度)
• 在整个应用程序中使用一致的公尺名称
• 使用 defaultDimensions 共享上下文(服务名称、环境)
• 偏爱 emitBatch 在一个请求中记录多个参数时
• 使用单元启用 Cloud Watch 仪表板中的自动转换
• 使用 child() 避免相关衡量尺度中重复维度

缩放成本( AWS)

• 摄取量 : Cloud Watch 通过EMF接受无限度量度——没有 API 调用限制
• 标准分辨率( 60s): 完全解析后保留15天,再汇总
• 高分辨率(1s): 完全解析后保留3小时,再汇总
• 费用: 具有独特的计量名称+尺寸组合的尺度(~0.30美元/度/月)
• 延迟 : EMF 在请求中添加了零延迟( studout write is no blocking)

地方发展

Metrics被写为EMF JSON来stdout——与AWS格式相同. 在本地dev中,可以在终端输出中看到公分量排放. 没有磁盘的持久性——衡量标准在当地是平面的(与KVStore或分布式表不同,它们坚持 .bb-data/) (中文(简体) ).

删去任何要重置的字句——没有当地的国家可以清除.