otel-go

Files (10)

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

SKILL.md (first lines)

# 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

| File | Use when |
|---|---|
| [`references/declarative-setup.md`](references/declarative-setup.md) | Configuring the SDK via `otelconf` and YAML: providers, propagators, shutdown, env-var substitution. |
| [`references/api.md`](references/api.md) | Looking up import paths, global API access, tracer/meter/logger usage, attributes, propagation, log bridges (zap, slog). |
| [`references/instrumentation-libraries.md`](references/instrumentation-libraries.md) | Picking or wiring contrib libraries (otelhttp, otelgrpc, database, AWS, message queues, propagators, resource detectors), and writing manual instrumentation that follows semconv. |
| [`references/performance.md`](references/performance.md) | Tuning sampling, batch processor, metric reader, exporter compression/retry, attribute allocation, log `Enabled()` short-circuiting, graceful shutdown. |
| [`references/breaking-changes.md`](references/breaking-changes.md) | Auditing existing code for deprecated calls, renamed semantic conventions, and removed APIs across recent SDK / contrib releases. |
| [`references/compile-time-instrumentation.md`](references/compile-time-instrumentation.md) | Zero-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 group | Example modules | Version 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 exporters | **v1.x** (e.g. v1.47.0; logs API/SDK joined at v1.47.0) |
| Log exporters and test helpers | `otel/exporters/otlp/otlplog/otlploghttp`, `.../otlploggrpc`, `otel/exporters/stdout/stdoutlog`, `otel/log/logtest`, `otel/sdk/log/logtest` | **v0.x** (separate, lower line, e.g. v0.23.0) |
| Contrib instrumentation | `contrib/instrumentation/net/http/otelhttp`, `.../otelgrpc` | **v0.x** (separate line, e.g. v0.72.0) |
| Contrib log bridges | `contrib/bridges/otelslog`, `otelzap`, `otellogrus`, `otellogr` | **v0.x** |

**The trap:** pinning every module to the core version (e.g. `go get go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp@v1.47.0`)
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:

```bash
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:

| Fact | Fetch |
|---|---|
| Latest `go.opentelemetry.io/otel` core release | `gh api repos/open-telemetry/opentelemetry-go/releases/latest -q '.tag_name'` |
| Latest `go.opentelemetry.io/contrib` release | `gh api repos/open-telemetry/opentelemetry-go-contrib/releases/latest -q '.tag_name'` |
| Latest `otelconf` module tag | the version-sorted tag command below the table |
| Latest Go semconv package | Search 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` CHANGELOG | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go/main/CHANGELOG.md` |
| `otel-go-contrib` CHANGELOG | `WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go-contrib/main/CHANGELOG.md` |

```bash
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.

From ollygarden/opentelemetry-agent-skills, Apache-2.0.

More from ollygarden/opentelemetry-agent-skills