鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

otel-instrument

根据代码变更自动扩展 OpenTelemetry 遥测能力,识别新增或修改的状态操作,按规范插入追踪点并记录指标,覆盖测试与文档更新,确保系统行为可观测。

开发运维
访问 GitHub
文档Skills.MD
name
OpenTelemetry Instrumentation Extension
description
Extend OpenTelemetry instrumentation when new functionality is added to the MCP Gateway. Use when (1) new operations/functions are added, (2) reviewing code for missing instrumentation, (3) user requests otel/telemetry additions, or (4) working with state-changing operations. Analyzes git diff, suggests instrumentation points following project standards in docs/telemetry/README.md, implements with approval, writes tests, updates documentation, and verifies with debug logging and docker logs.

OpenTelemetry Instrumentation Extension

Automatically extend OpenTelemetry instrumentation for new functionality in the MCP Gateway, following established patterns documented in docs/telemetry/README.md.

When to Use This Skill

Automatically apply when:

  • New state-changing operations added (Create, Update, Delete, Push, Pull, Add, Remove, etc.)
  • New CLI commands added to cmd/docker-mcp/
  • New packages with operations in pkg/
  • User mentions "otel", "telemetry", "instrumentation", "metrics", or "tracing"
  • Code changes that modify state (database, files, containers, configuration)
  • Reviewing code for telemetry coverage

Workflow

Phase 1: Analysis & Suggestion

  1. Read project telemetry standards:

    • Read docs/telemetry/README.md "Development Guidelines" section
    • Read pkg/telemetry/telemetry.go to understand existing patterns and metrics
  2. Identify scope using git diff:

    • Find new/changed files in pkg/ and cmd/docker-mcp/
    • Identify functions performing state-changing operations
    • Infer domain from package structure (e.g., pkg/foo/ → domain: foo)
  3. Categorize findings:

    • Operations in existing domains (use existing metrics)
    • Operations in new domains (need new metrics)
  4. Present suggestions to user:

    • List each function needing instrumentation with file:line reference
    • Specify operation type (create, update, delete, etc.)
    • Identify domain and whether metrics exist
    • Show what will be added (instrumentation code, metrics, docs, tests)

Phase 2: Implementation (After User Approval)

Execute in this order:

  1. Make changes: Instrument operations and add metrics to pkg/telemetry/telemetry.go
  2. Verify: Build, run with OTEL collector, check docker logs otel-debug output
  3. Write tests: Add tests to pkg/telemetry/telemetry_test.go
  4. Update docs: Add metrics/operations to docs/telemetry/README.md
  5. Run tests: Execute make test
  6. Final verification: Run ./docs/telemetry/testing/test-telemetry.sh

Key Principles

Follow the project's documented guidelines from docs/telemetry/README.md:

  1. Use Existing Providers: Get global tracer/meter from OTEL
  2. Preserve Server Lineage: Include server attribution in all telemetry
  3. Non-Blocking Operations: Telemetry never blocks or fails operations
  4. Debug Support: Add logging behind DOCKER_MCP_TELEMETRY_DEBUG
  5. Follow Naming Conventions: Use mcp.<domain>.<field> pattern
  6. Deferred Success Tracking: Only set success on clean completion

Where to Find Information

ALWAYS read these files before suggesting changes:

  1. docs/telemetry/README.md - Source of truth for:

    • Development guidelines (lines 419-474)
    • Existing metrics and attributes
    • Testing procedures
    • Naming conventions
  2. pkg/telemetry/telemetry.go - Understand:

    • Existing metric instruments
    • Recording function patterns
    • Helper functions for spans
    • Init() structure
  3. pkg/telemetry/telemetry_test.go - See:

    • Testing patterns
    • How to verify metrics

Instrumentation Pattern

Use the simple defer pattern from cmd/docker-mcp/catalog/create.go:

▼
go
复制代码
func OperationName(ctx context.Context, identifier string, ...) error { telemetry.Init() start := time.Now() var success bool defer func() { duration := time.Since(start) telemetry.Record<Domain>Operation(ctx, "operation_name", identifier, float64(duration.Milliseconds()), success) }() // ... operation logic ... // Optional: Record resource counts telemetry.Record<Domain><Resources>(ctx, identifier, int64(count)) success = true return nil }

Note: If identifier is generated during execution, the defer captures its final value.

Adding New Domains

When instrumentation is needed for a new domain (e.g., new package pkg/newdomain/):

1. Add Metric Instruments in pkg/telemetry/telemetry.go

In the Init() function, add global variables and create metric instruments:

▼
go
复制代码
var ( // ... existing metrics ... // New domain metrics newdomainOperations metric.Int64Counter newdomainOperationDuration metric.Float64Histogram newdomainResources metric.Int64Gauge // If managing resources ) func Init() { // ... existing init code ... newdomainOperations, _ = meter.Int64Counter( "mcp.newdomain.operations", metric.WithDescription("New domain operations count"), ) newdomainOperationDuration, _ = meter.Float64Histogram( "mcp.newdomain.operation.duration", metric.WithDescription("New domain operation duration in milliseconds"), ) newdomainResources, _ = meter.Int64Gauge( "mcp.newdomain.resources", metric.WithDescription("Number of resources in new domain"), ) }

2. Add Recording Functions in pkg/telemetry/telemetry.go

After the Init() function, add recording functions:

▼
go
复制代码
func RecordNewdomainOperation(ctx context.Context, operation, identifier string, durationMs float64, success bool) { if newdomainOperations == nil || newdomainOperationDuration == nil { return } attrs := []attribute.KeyValue{ attribute.String("mcp.newdomain.operation", operation), attribute.String("mcp.newdomain.id", identifier), // or .name, .ref as appropriate attribute.Bool("mcp.newdomain.success", success), } newdomainOperations.Add(ctx, 1, metric.WithAttributes(attrs...)) newdomainOperationDuration.Record(ctx, durationMs, metric.WithAttributes(attrs...)) } // Optional: Add resource counting function if applicable func RecordNewdomainResources(ctx context.Context, identifier string, count int64) { if newdomainResources == nil { return } attrs := []attribute.KeyValue{ attribute.String("mcp.newdomain.id", identifier), } newdomainResources.Record(ctx, count, metric.WithAttributes(attrs...)) }

3. Write Tests in pkg/telemetry/telemetry_test.go

Add test cases following existing patterns:

▼
go
复制代码
func TestRecordNewdomainOperation(t *testing.T) { spanRecorder, metricReader := setupTestTelemetry(t) Init() ctx := context.Background() // Test successful operation RecordNewdomainOperation(ctx, "create", "test-id", 123.45, true) // Collect and verify metrics var rm metricdata.ResourceMetrics err := metricReader.Collect(ctx, &rm) require.NoError(t, err) // Find and verify the counter metric foundCounter := false foundHistogram := false for _, sm := range rm.ScopeMetrics { for _, m := range sm.Metrics { if m.Name == "mcp.newdomain.operations" { foundCounter = true sum := m.Data.(metricdata.Sum[int64]) require.Len(t, sum.DataPoints, 1) assert.Equal(t, int64(1), sum.DataPoints[0].Value) // Verify attributes attrs := sum.DataPoints[0].Attributes assert.Contains(t, attrs.ToSlice(), attribute.String("mcp.newdomain.operation", "create")) assert.Contains(t, attrs.ToSlice(), attribute.String("mcp.newdomain.id", "test-id")) assert.Contains(t, attrs.ToSlice(), attribute.Bool("mcp.newdomain.success", true)) } if m.Name == "mcp.newdomain.operation.duration" { foundHistogram = true histogram := m.Data.(metricdata.Histogram[float64]) require.Len(t, histogram.DataPoints, 1) assert.Equal(t, float64(123.45), histogram.DataPoints[0].Sum) } } } assert.True(t, foundCounter, "Counter metric not found") assert.True(t, foundHistogram, "Histogram metric not found") }

4. Update Documentation in docs/telemetry/README.md

Add a new section for the domain in the appropriate location. Follow the existing format:

▼
markdown
复制代码
### New Domain Operations Operations for managing [description of what this domain does]: - **`mcp.newdomain.operations`** - New domain operations (create, update, delete, etc.) - **`mcp.newdomain.operation.duration`** - Duration of new domain operations - **`mcp.newdomain.resources`** - Gauge showing number of resources in new domain #### New Domain Attributes - **`mcp.newdomain.operation`** - Type of operation (create, update, delete, etc.) - **`mcp.newdomain.id`** - ID of the resource - **`mcp.newdomain.success`** - Boolean indicating operation success

Verification

After making changes, verify telemetry output:

▼
bash
复制代码
# Build make docker-mcp # Start OTEL collector docker run --rm -d --name otel-debug \ -p 4317:4317 -p 4318:4318 \ -v $(pwd)/docs/telemetry/testing/otel-collector-config.yaml:/config.yaml \ otel/opentelemetry-collector:latest --config=/config.yaml # Run with telemetry enabled export DOCKER_MCP_TELEMETRY_DEBUG=1 export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 docker mcp [command] # Check collector output docker logs otel-debug | grep "mcp.newdomain" # Cleanup docker stop otel-debug

Verify the output matches expectations before proceeding to write tests and docs.

Analysis Strategy

When analyzing git diff:

  1. Look for operation verbs in function names:

    • Create, Add, Update, Modify, Set, Configure, Register
    • Delete, Remove, Unregister, Clear
    • Push, Pull, Export, Import, Sync
    • Start, Stop, Run, Execute
  2. Look for state changes:

    • Database operations (DAO/DB calls)
    • File system operations (create, delete, write)
    • Container operations (start, stop, create, delete)
    • Configuration changes (save, update)
  3. Infer domain from file path:

    • pkg/workingset/ → domain: profile
    • pkg/catalog_next/ → domain: catalog_next
    • cmd/docker-mcp/server/ → domain: server
    • Pattern: use logical grouping name
  4. Check if telemetry exists:

    • Search pkg/telemetry/telemetry.go for Record<Domain> functions
    • If exists: use existing metrics
    • If not: propose new domain metrics

Implementation Checklist

Follow this sequence:

  • Read patterns from docs/telemetry/README.md
  • Instrument operations with simple defer pattern
  • Add new metrics to pkg/telemetry/telemetry.go (if new domain)
  • Verify with docker logs otel-debug - confirm output matches expectations
  • Write tests in pkg/telemetry/telemetry_test.go
  • Update docs/telemetry/README.md with new metrics
  • Run make test - verify tests pass
  • Run ./docs/telemetry/testing/test-telemetry.sh - final verification

Important Notes

  • Read documentation first
  • Follow existing patterns
  • Ask for approval before implementing
  • Verify early and often with collector logs
开发运维

快捷安装

复制到终端去安装 Skill

npxskillsadddocker/mcp-gateway--skill"otel-instrument"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
load-balancer-configurator
根据用户需求自动生成各类负载均衡器的生产级配置,覆盖 ALB、NLB、Nginx 和 HAProxy 等主流类型,适配不同协议、端口、健康检查及后端服务拓扑,支持直接集成到基础设施即代码流程中。
implement
实现 Linus Dashboard 的功能开发与集成,基于 TypeScript 和 Python 构建前后端组件,遵循严格的代码规范与架构模式,完成视图、卡片、服务及传感器等模块的创建与验证,确保高质量交付并兼容 Home Assistant 生态。
cloud-scheduler-job-creator
自动处理 Google Cloud Platform 中的云调度任务创建,提供符合最佳实践的配置方案与生产级代码生成,支持计算、存储、大数据及机器学习服务的集成部署。