{"slug":"otel-profiles","title":"otel-profiles","summary":"OpenTelemetry profiles signal and the eBPF profiler (otelcol-ebpf-profiler, `profiling` receiver). Use when setting up continuous profiling with OpenTelemetry, deploying the eBPF profiler on Linux hosts, Docker, or Kubernetes (DaemonSet, kind, k3d), building a profiles pipeline, ","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-16T16:29:04.578405Z","repo":{"url":"https://github.com/ollygarden/opentelemetry-agent-skills","stars":111,"forks":13,"license":"Apache-2.0","updatedAt":"2026-10-16T08:07:28Z"},"bodyHtml":"
\n

name: otel-profiles\ndescription: OpenTelemetry profiles signal and the eBPF profiler (otelcol-ebpf-profiler, profiling receiver). Use when setting up continuous profiling with OpenTelemetry, deploying the eBPF profiler on Linux hosts, Docker, or Kubernetes (DaemonSet, kind, k3d), building a profiles pipeline, sending OTLP profiles to Pyroscope, Grafana Cloud Profiles, or another backend, getting flame graphs from OTel, enabling off-CPU profiling, or debugging profiler errors about tracefs, PID namespaces, missing pods, or the service.profilesSupport feature gate. Not for SDK tracing or metrics setup.

\n

OpenTelemetry Profiles

\n

The main OpenTelemetry producer is the eBPF profiler, shipped as the profiling receiver in the otelcol-ebpf-profiler Collector distribution. It profiles every process on a Linux host with no application changes.

\n

Maturity: the signal entered public Alpha in March 2026, the OTLP profiles proto (v1development) is Development, the profiling receiver is Development, and the Collector gate service.profilesSupport is alpha. Expect breaking changes; pin the profiler, Collector, and backend versions together.

\n

Collector-side component facts (OTLP receiver/exporter profile support, the fixed /v1development/profiles HTTP path, k8s_attributes, memory_limiter, filter profile_conditions) live in the otel-collector skill's component pages; OTTL profile/profilesample contexts live in otel-ottl.

\n

otelcol-ebpf-profiler 0.162.0 bundles only: receivers profiling, nop; processors memory_limiter, k8s_attributes, resource_detection, resource, transform (plus batch, which does not support profiles); exporters otlp_grpc, otlp_http, debug, file, nop; extensions health_check, pprof, opamp. For anything else (filter, the basicauth extension, vendor exporters), relay to a regular Collector or build a distribution (otel-collector-builder skill).

\n

Version matrix (Verified 2026-10-15)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ArtifactVersionWhat it means
otel/opentelemetry-collector-ebpf-profiler0.162.0 (newest release at verification, 2026-09-29)Pins ebpf-profiler v0.0.202636: boolean pid_namespace_translation; does not bundle the offcpu extension.
Same image, 0.163.0-nightly.*prereleaseBundles offcpu from 0.163.0-nightly.3d037de (2026-10-05); pins ebpf-profiler v0.0.202640, with pid_namespace_translation_mode (#1801), from 0.163.0-nightly.2e6f5c3 (2026-10-07). Release 0.163.0 is unpublished; until it is, these need a nightly or an OCB build.
\n

Evidence: Docker Hub tags (no 0.163.0), collector-releases (latest v0.162.0), the distribution manifest history.

\n

Read references/receiver.md when setting keys beyond samples_per_second, enabling off-CPU or OBI correlation, or pinning a release not in this table (keys follow the pinned ebpf-profiler, not the Collector version).

\n

Workflow

\n
    \n
  1. Pick the image and pin. Use the latest release unless a needed key or component is missing from it (see the matrix). Alternatives: a pinned nightly, labeled as a prerelease with the release that replaces it, or an OCB build (otel-collector-builder skill) based on the distribution manifest.
    2. \n
  2. Pick the environment.\n\n
    3. \n
  3. Wire the pipeline. profiles pipeline: profiling receiver, memory_limiter first, enrichment processors, then otlp_grpc or otlp_http. Start the Collector with --feature-gates=+service.profilesSupport. Run validate --config=<file> --feature-gates=+service.profilesSupport with the target image; it catches wrong keys for the pinned version.
    4. \n
  4. Export and verify. Add debug (verbosity: basic) first: each reporter_interval it logs \"resource profiles\": N, \"sample records\": M; no lines or zero counts mean the receiver is not producing (see troubleshooting). verbosity: detailed shows resource attributes. Then add the backend: references/backends.md for endpoints, auth, and per-backend label behavior.
    5. \n
  5. Troubleshoot by exact error string: references/troubleshooting.md.
    6. \n
\n

Run on a host

\n

The profiler needs root or CAP_SYS_ADMIN/CAP_BPF/CAP_PERFMON, the host PID namespace, and a mounted tracefs. A container gets a fresh /sys without tracefs even when privileged, so bind-mount it:

\n
docker run -d --name otel-ebpf-profiler --privileged --pid=host \\\n  -v /sys/kernel/tracing:/sys/kernel/tracing \\\n  -v \"$PWD/config.yaml:/etc/otelcol/config.yaml:ro\" \\\n  otel/opentelemetry-collector-ebpf-profiler:0.162.0 \\\n  --config=/etc/otelcol/config.yaml --feature-gates=+service.profilesSupport\n
\n
receivers:\n  profiling:\n    samples_per_second: 20      # default\nprocessors:\n  memory_limiter:\n    check_interval: 1s\n    limit_mib: 800\n    spike_limit_mib: 200\nexporters:\n  debug:\n    verbosity: basic\n  otlp_grpc:\n    endpoint: profiles-backend:4317   # backend-specific, see references/backends.md\n    tls:\n      insecure: true\nservice:\n  pipelines:\n    profiles:\n      receivers: [profiling]\n      processors: [memory_limiter]\n      exporters: [otlp_grpc, debug]\n
\n

The image is built FROM scratch: no shell, so debug from logs, not exec. Expected startup lines: eBPF tracer loaded, Attached sched monitor, Everything is ready.

\n

Known limitations

\n\n","files":[{"path":"evals/evals.json","sizeBytes":9366,"isText":true},{"path":"references/backends.md","sizeBytes":5267,"isText":true},{"path":"references/kubernetes.md","sizeBytes":7047,"isText":true},{"path":"references/nested-containers.md","sizeBytes":3199,"isText":true},{"path":"references/receiver.md","sizeBytes":3209,"isText":true},{"path":"references/troubleshooting.md","sizeBytes":5112,"isText":true},{"path":"SKILL.md","sizeBytes":7482,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-16T16:32:43.576584Z","sha256":"9DC01A32E5E16484193F78A1EA49832D503ADDD1E1BF92A202BD8F937B172214","sizeBytes":17580},"review":null,"source":{"repositoryUrl":"https://github.com/ollygarden/opentelemetry-agent-skills","path":"skills/otel-profiles","license":"Apache-2.0","commit":"967179521de5e8dac365ae6fbc4fc64f427259f5","subtreeSha":"A1D85C81E1FE8E7E52F33DEBAFD5C061A3E5EDF96158A18C588F2CB1BD24CADC","lastSyncedAt":"2026-10-16T16:29:03.891055Z"},"reviewedAt":"2026-10-16T16:40:03.596025Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/ollygarden/opentelemetry-agent-skills/tree/main/skills/otel-profiles"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install ollygarden-opentelemetry-agent-skills@llmmart"},{"target":"git","command":"git clone https://github.com/ollygarden/opentelemetry-agent-skills.git"}]}