mcpField
O
opentelemetry

opentelemetry

github.com/claude-dev-suite云与 DevOps4642 次安装3 天前更新
代码仓库

关于 opentelemetry

为使用 OpenTelemetry 进行 Node.js 和 Spring Boot 应用监控提供速查资料，涵盖追踪、指标、日志、配置、采样与故障排查，适合负责接入可观测性的开发者。

主要功能

  1. 01Node.js SDK 配置
  2. 02Spring Boot 追踪配置
  3. 03手动创建 Span
  4. 04OTLP 导出器配置
  5. 05采样与故障排查

适用场景

  1. 01为服务添加分布式追踪
  2. 02配置通过 OTLP 导出遥测数据
  3. 03排查追踪缺失或内存占用过高

MCP 相关

该技能引用 `mcp__documentation__fetch_docs` 获取完整的 OpenTelemetry 文档。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/claude-dev-suite/claude-dev-suite --skill opentelemetry

安装后在 Claude Code 中输入/opentelemetry确认已加载。

附带文件advanced.md

详细介绍

OpenTelemetry - 快速参考

完整参考：有关上下文传播、详细的指标 API、Collector 配置、Docker Compose 堆栈、采样策略和语义约定，请参阅 advanced.md。

深入了解：使用技术名称为 opentelemetry 的 mcp__documentation__fetch_docs 获取全面的文档。

概念

┌─────────────────────────────────────────────────────────────┐
│                      OpenTelemetry                          │
├─────────────────┬─────────────────┬─────────────────────────┤
│     Traces      │     Metrics     │         Logs            │
│  (Distributed)  │  (Aggregated)   │     (Structured)        │
├─────────────────┴─────────────────┴─────────────────────────┤
│                    OTLP Protocol                            │
├─────────────────────────────────────────────────────────────┤
│                 Collector (optional)                        │
├─────────────────────────────────────────────────────────────┤
│  Jaeger │ Zipkin │ Prometheus │ Grafana │ DataDog │ etc.    │
└─────────────────────────────────────────────────────────────┘

Node.js 设置

npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http
基本配置
// tracing.ts - Load FIRST before any other imports
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'my-service',
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown().finally(() => process.exit(0));
});
应用程序入口点
// index.ts
import './tracing'; // MUST be first import
import express from 'express';

const app = express();

手动追踪

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service', '1.0.0');

async function processOrder(orderId: string) {
  return tracer.startActiveSpan('process-order', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      await processOrderLogic(orderId);
      span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  });
}

Spring Boot 设置

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

环境变量

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1  # 10% sampling

不适用此技能的情况

  • 简单的应用程序日志记录：改用日志记录框架
  • 单体应用程序：可能有些大材小用
  • 特定于供应商的 APM：DataDog、New Relic 有自己的 SDK
  • 仅用于开发/调试：标准日志记录可能就足够了
  • 遗留系统：迁移成本可能很高

反模式

反模式缺点解决方案
为每个函数创建 span开销巨大仅为有意义的操作创建 span
在生产环境中进行 100% 采样影响性能，增加成本使用 1-10% 的采样率
不传播上下文导致分布式追踪中断在服务边界注入/提取上下文
在 span 属性中记录 PII违反安全/合规要求过滤敏感数据
忘记结束 span内存泄漏始终在 finally 块中结束 span
使用同步导出器阻塞应用程序使用批处理器

快速故障排除

问题原因解决方案
未显示追踪数据未配置导出器检查 OTEL_EXPORTER_OTLP_ENDPOINT
内存使用量过高span 过多启用采样
上下文传播缺失未注入标头使用传播 API
性能下降采样率过高降至 1-10%
SDK 初始化错误导入顺序错误在其他导入之前初始化 SDK

监控指标

指标目标
追踪延迟（p99）< 10ms 开销
span 丢弃率< 1%
Collector 内存< 1GB
导出成功率> 99%

检查清单

  • 在其他导入之前初始化 SDK
  • 配置资源属性
  • 实现上下文传播
  • 定义采样策略
  • 配置优雅关闭
  • 部署 Collector
  • 创建仪表板（Grafana）
  • 配置告警

参考

深入了解：使用技术名称为 opentelemetry 的 mcp__documentation__fetch_docs 获取全面的文档

评论

支持 Markdown