mcpField
O
otel-go

otel-go

github.com/ollygardenDevelopment117131 installsUpdated 2d ago
Repository

About otel-go

otel-go is a reference skill for using OpenTelemetry in Go services. It helps Go developers configure and instrument telemetry, tune performance, and review SDK or contrib upgrades, with guidance on module versioning and local verification.

Key features

  1. 01Declarative SDK setup with YAML
  2. 02API usage and instrumentation guidance
  3. 03Performance tuning references
  4. 04Breaking-change and upgrade checks
  5. 05Compile-time instrumentation with otelc

Use cases

  1. 01Adding telemetry to a Go service
  2. 02Choosing instrumentation libraries
  3. 03Reviewing OpenTelemetry dependency upgrades

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ollygarden/opentelemetry-agent-skills --skill otel-go

After installing, type/otel-goin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

evals/
evals.json
results.md
evals/files/
go-v145-upgrade.md
references/
api.md
breaking-changes.md
compile-time-instrumentation.md
declarative-setup.md
instrumentation-libraries.md
performance.md

Details

From the project README

OpenTelemetry in Go

Entry point for OpenTelemetry mechanics in Go services. Load a reference below based on the task; each reference is self-contained.

References

FileUse when
references/declarative-setup.mdConfiguring the SDK via otelconf and YAML: providers, propagators, shutdown, env-var substitution.
references/api.mdLooking up import paths, global API access, tracer/meter/logger usage, attributes, propagation, log bridges (zap, slog).
references/instrumentation-libraries.mdPicking or wiring contrib libraries (otelhttp, otelgrpc, database, AWS, message queues, propagators, resource detectors), and writing manual instrumentation that follows semconv.
references/performance.mdTuning sampling, batch processor, metric reader, exporter compression/retry, attribute allocation, log Enabled() short-circuiting, graceful shutdown.
references/breaking-changes.mdAuditing existing code for deprecated calls, renamed semantic conventions, and removed APIs across recent SDK / contrib releases.
references/compile-time-instrumentation.mdZero-code, compile-time instrumentation with otelc: usage modes (otelc go build, tool dependency, toolexec drop-in), subcommands, supported libraries, rule sources/precedence, and pinning via otel.instrumentation.go.

For upgrade reviews, always finish with a safe local verification path (go mod tidy -diff, go build ./..., and go test ./...). Test exporter URL or retry changes against a disposable local receiver, never a deployment endpoint.

Module versioning — read before adding dependencies

opentelemetry-go is split into independently versioned module groups. They do NOT share one version number. Assuming they do is the most common cause of broken builds and version churn:

Module groupExample modulesVersion line
Stable (traces, metrics, logs API/SDK)go.opentelemetry.io/otel, otel/sdk, otel/trace, otel/metric, otel/log, otel/sdk/log, OTLP trace/metric exportersv1.x (e.g. v1.47.0; logs API/SDK joined at v1.47.0)
Log exporters and test helpersotel/exporters/otlp/otlplog/otlploghttp, .../otlploggrpc, otel/exporters/stdout/stdoutlog, otel/log/logtest, otel/sdk/log/logtestv0.x (separate, lower line, e.g. v0.23.0)
Contrib instrumentationcontrib/instrumentation/net/http/otelhttp, .../otelgrpcv0.x (separate line, e.g. v0.72.0)
Contrib log bridgescontrib/bridges/otelslog, otelzap, otellogrus, otellogrv0.x

The trap: pinning every module to the core version (e.g. go get go.opentelemetry.io/otel/exporters/otlp/otlplog/[email protected]) fails — log exporter, log test-helper, and bridge modules have no v1.x tag. Hand-picking and re-guessing each @vX is the churn to avoid.

Do this instead — add each module with @latest and let Go resolve a compatible set:

go get go.opentelemetry.io/otel@latest go.opentelemetry.io/otel/sdk@latest
# logs (API/SDK are v1.x; log exporters stay on a v0.x line — do NOT force the core version):
go get go.opentelemetry.io/otel/log@latest go.opentelemetry.io/otel/sdk/log@latest \
       go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp@latest
# contrib (instrumentation and bridges each resolve to their own v0.x line):
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@latest \
       go.opentelemetry.io/contrib/bridges/otelslog@latest
go mod tidy && go build ./...

If exact versions are required, fetch each module group's tag from its own source (see below) — never infer one group's version from another's.

Sources of Truth

For YAML schema details, fetch the upstream sources listed in the otel-declarative-config skill. For Go-specific facts:

FactFetch
Latest go.opentelemetry.io/otel core releasegh api repos/open-telemetry/opentelemetry-go/releases/latest -q '.tag_name'
Latest go.opentelemetry.io/contrib releasegh api repos/open-telemetry/opentelemetry-go-contrib/releases/latest -q '.tag_name'
Latest otelconf module tagthe version-sorted tag command below the table
Latest Go semconv packageSearch the selected core release's CHANGELOG for Add the go.opentelemetry.io/otel/semconv/; do not infer package availability from the upstream semantic-conventions release. Offline: semconv/v1.43.0 in otel v1.47.0, verified 2026-10-25 (record: the otel-semantic-conventions skill's references/sdk-semconv-packages.md).
otel-go CHANGELOGWebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go/main/CHANGELOG.md
otel-go-contrib CHANGELOGWebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go-contrib/main/CHANGELOG.md
gh api repos/open-telemetry/opentelemetry-go-contrib/git/matching-refs/tags/otelconf -q '.[].ref' | sort -V | tail -1

Cross-References

  • Schema-level facts: otel-declarative-config skill (language-agnostic YAML schema sources).
  • SDK version selection across languages: otel-sdk-versions skill.
  • Semantic conventions lookup: otel-semantic-conventions skill.

Comments

Markdown supported