工人可观察性

用于从Cloudflare工人那里捕捉和输出度量衡和日志的轻量级包.

特征

• 通过可配置的尾矿工人向多汇(Datadog、工人分析引擎、OpenTeleometry)集中出口
• 全面的衡量支持: COUNT, (中文(简体) ), GAUGE,以及 HISTOGRAM 自动汇总和标记
• 土著 console.log() 支持 - 与现有日志合作, 无需更改代码

基本用途

在员工中设置计量

主要工人将收集衡量标准并通过诊断渠道公布。 这个 metrics 对象提供了不同类型度量衡的记录方法:

import { metrics } from '@flarelabs-net/workers-observability-utils';

export default {
  async fetch(request, env, ctx) {
    // Record count metric with tags
    metrics.count('worker.request', 1, {
      method: request.method,
    });

    // Record gauge metric
    metrics.gauge('worker.connections.active', 42);

    // Record histogram metric for response time.
    // Note: Timers are not totally accurate in cloudflare worker environments
    // but this can give an indication of relative performance
    const startTime = Date.now();
    const response = await processRequest();
    const responseTime = Date.now() - startTime;
    metrics.histogram('worker.response_time', responseTime, {
      percentiles: [0.5, 0.95, 0.99],
      aggregates: ['avg', 'max']
    });

    return response;
  },
};

计量类型

这个库支持三种计量标准:

1. 库恩特 - 事件总数。 可以增减. (例如请求计数,错误计数)

   metrics.count('worker.request', 1, { status: '200' });
   

2. 乔治 - 时间点测量(例如内存使用、连接计数)

   metrics.gauge('worker.memory_usage', memoryUsage, { region: 'earth' });
   

3. 中国 - 随时间推移的数值分布,统计汇总

   metrics.histogram('worker.response_time', responseTimeMs, {
     percentiles: [0.5, 0.95, 0.99],  // p50, p95, and p99 percentiles
     aggregates: ['avg', 'max', 'min', 'sum', 'count']
   }, { endpoint: '/api' });
   

   直方图量度自动生成多个衍生量度 :

   • 百分率(测量): worker.cpu_time.p50, (中文(简体) ), worker.cpu_time.p95等 (中文(简体) ).
   • 合计数 : worker.cpu_time.avg, (中文(简体) ), worker.cpu_time.max等 (中文(简体) ).

标记

所有度量衡都支持标记,它们是帮助分类和过滤度量的密钥值对:

metrics.count('worker.request', 1, {
  method: 'GET',
  path: '/api',
  status: '200'
});

在工作人中设置日志

此库自动抓取全部 console.log() 您的员工打来的电话 - 不需要更改代码 ! 您的现有采伐将通过"尾矿工人"进行收集和出口.

export default {
  async fetch(request, env, ctx) {
    // These logs will be automatically captured and exported
    console.log('Processing request', { method: request.method, url: request.url });
    console.error('Something went wrong', { error: 'details' });
    console.warn('This is a warning');
    
    return new Response('Hello World');
  },
};

日志辛克

目前支持的日志目的地 :

• 打开几何 - 将日志转发给任何可兼容的 OpenTeleometry 收藏器

设置尾线工人

为了高效地向外部供应商输出计量标准,您应当设置专门的"尾矿工人". 这个架构允许您的主要工人专注于处理请求,而"尾矿工人"则处理计量收集和导出. 更多信息,请参见 云花纹工人文件。 。 。 .

多个辛克

通过这个库,您可以同时向多个目的地发送度量衡. TailExporter支持一系列的公制汇,每个汇都得到相同的公制汇数据. 目前得到支持的汇包括:

• 数据犬 - 向Datadog输出用于可视化和报警的衡量标准
• 工人分析引擎 - Cloudflare's Analytics engine中存储用于自定义查询和分析的度量衡 - Warning:每个请求给工人分析引擎的默认写作数量为25.
• 奥特计量器 - 将你的量子发送给任何可兼容的 OpenTeleometry 收藏器

在使用多汇时,将同时向所有配置的汇发送指标。 如果一个沉没,其他的仍然会得到测量值.

尾矿工人配置

1. 创建处理尾端事件的新工作者 :

// tail-worker/src/index.ts
import { TailExporter, DatadogMetricSink, WorkersAnalyticsEngineSink, OtelMetricSink, OtelLogSink } from '@flarelabs-net/workers-observability-utils';

export default new TailExporter({
  metrics: {
    sinks: [
      new DatadogMetricSink({
        site: 'us3.datadoghq.com',
        // API key can be provided here or via environment variables
        // apiKey: 'your-datadog-api-key'
      }),
      new WorkersAnalyticsEngineSink({
        datasetBinding: env.ANALYTICS_ENGINE_DATASET
      }),
      new OtelMetricSink({
                url: 'https://my-otel-exporter.io',
                headers: {
                    
                },
            }),
    ],
    // Optional default metrics to collect automatically
    defaultMetrics: {
      cpuTime: true,           // default: true - collects worker.cpu_time as a GAUGE
      wallTime: true,          // default: true - collects worker.wall_time as a GAUGE
      workersInvocation: true, // default: true - collects worker.invocation as a COUNT
    },
    // When using Workers Analytics Engine, a value of 20 or less is recommended due to soft limits
    maxBufferSize: 20,
    // Maximum duration in seconds to buffer before flushing (default: 5, max: 30)
    maxBufferDuration: 5
  },
  logs: {
    sinks: [
      new OtelLogSink({
                url: 'https://my-otel-exporter.io',
                headers: {
                    
                },
                defaultLogsEnabled: {
                    invocationLog: true;
                };
            }),
    ],
    maxBufferSize: 20,
    maxBufferDuration: 5
  }
});

默认日志

尾端导出器可以通过每根汇发送一小组内置登录 defaultLogsEnabled 选项(用于汇,例如 OtelLogSink) (中文(简体) ). 最常见的默认日志是:

• invocationLog (默认 : true:发布每集引用日志记录,包含关于引用的元数据(书写名称,执行模式,结果,版本Id),计时信息和任何全局标记. 这补充了自动 console 用于追踪、审计和将衡量标准与个人援引联系起来.

要禁用汇的引用日志, 设置 :

new OtelLogSink({
  ...
  defaultLogsEnabled: {
    invocationLog: false;
  };
}),

您可以在构建汇时启用或禁用每个汇的默认日志(参见 OtelLogSink (见上文实例).

2. 设置 Datadog API 键 :

# Using wrangler secrets
wrangler secret put DD_API_KEY
# Or DATADOG_API_KEY is also supported

2. 配置您的工人 :

// wrangler.jsonc for the Emitting Worker
{
  "name": "my-worker",
  // Required: Enable the tail_consumers configuration
  "tail_consumers": [
    {
      "service": "name-of-tail-worker",
    }
  ]
}

环境变量和约束

尾矿工人支持下列环境变量和约束:

数据犬

• DD_API_KEY: 您的数据犬 API 密钥
• DD_SITE: datadog url 即 us3. datadoghq.com 数据犬url :

工人分析引擎

• 需要将分析引擎数据集装入您的 wrangler.jsonc 中:

{
  "analytics_engine_datasets": [
    {
      "binding": "ANALYTICS_ENGINE_DATASET",
      "dataset": "your-dataset-name"
    }
  ]
}

说明:工人分析引擎每引用一个软限为25个字,所以建议在使用这个水槽时,将您的最大缓冲度保持在20或更低.

默认计量

尾线工人可以自动收集以下的度量衡,而无需在您的主要工人中安装任何仪器:

1. CPU 时间 (单位:千美元)worker.cpu_time- 测量工人用毫秒计的CPU时间的GAUGE计量标准
2. 墙壁时间 (单位:千美元)worker.wall_time以毫秒计算工人总执行时间的GAUGE指标
3. 利用工人 (单位:千美元)worker.invocation- 参照每个工人增加1倍的COUNT指标

这些度量衡是用同样的全局标记来收集的,这些标记应用于您的自定义度量衡(scriptName, executionModel, result, versionId).

您可以启用或禁用 TailExporter 配置中的这些默认度量 :

export default new TailExporter({
  metrics: {
    sinks: [...],
    defaultMetrics: {
      cpuTime: true,           // default: true
      wallTime: true,          // default: true
      workersInvocation: true, // default: true
    }
  }
});