{"id":19259012,"url":"https://github.com/polarsignals/otel-profiling-go","last_synced_at":"2025-04-21T16:30:37.005Z","repository":{"id":226053852,"uuid":"767058687","full_name":"polarsignals/otel-profiling-go","owner":"polarsignals","description":"Easily connect distributed tracing with profiling data.","archived":false,"fork":false,"pushed_at":"2024-10-15T16:37:12.000Z","size":4537,"stargazers_count":14,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-20T12:15:30.098Z","etag":null,"topics":["distributed-tracing","go","golang","opentelemetry","opentelemetry-go","pprof","profiling","tracing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polarsignals.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-04T16:22:39.000Z","updated_at":"2024-10-15T16:37:15.000Z","dependencies_parsed_at":"2024-03-05T17:22:39.849Z","dependency_job_id":null,"html_url":"https://github.com/polarsignals/otel-profiling-go","commit_stats":null,"previous_names":["polarsignals/otel-profiling-go"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarsignals%2Fotel-profiling-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarsignals%2Fotel-profiling-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarsignals%2Fotel-profiling-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarsignals%2Fotel-profiling-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polarsignals","download_url":"https://codeload.github.com/polarsignals/otel-profiling-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250090635,"owners_count":21373221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-tracing","go","golang","opentelemetry","opentelemetry-go","pprof","profiling","tracing"],"created_at":"2024-11-09T19:15:04.149Z","updated_at":"2025-04-21T16:30:36.189Z","avatar_url":"https://github.com/polarsignals.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# otel-profiling-go\n\nThis package provides an integration between distributed tracing via OpenTelemetry with Profiling data collected via eBPF by [Parca Agent](https://github.com/parca-dev/parca-agent). The best thing about this is that it isn't actually a deep integration with Parca Agent, it just puts the trace ID into a place that Parca Agent will know how to find.\n\n\u003e Note: Currently Parca Agent only supports reading the trace ID in Go 1.22.\n\nMore specifically it provides three ways to do so:\n\n* An OpenTelemetry `Tracer` implementation\n* A gRPC middleware\n* An HTTP middleware\n\nWhat these provide are ways to automatically [set Go's goroutine labels](https://pkg.go.dev/runtime/pprof#SetGoroutineLabels). Goroutine labels are then accessible to Parca Agent via eBPF, as they are stored in thread-local-store, which the Go runtime manages, which has a well-known layout, so it is easy for the Parca Agent to know how to read them.\n\n## Using the Tracer\n\nThe tracer is the simplest way to get started, as it can be used as a drop-in replacement for your existing tracer, and you're all set! The tracer is also the least efficient, as it causes allocations with every new span that's created.\n\n```go\nimport (\n\totelprof \"github.com/polarsignals/otel-profiling-go\"\n)\n\nmain() {\n\ttp := initTracer()\n\totel.SetTracerProvider(otelprof.NewTracerProvider(tp))\n\n\t// your application...\n}\n```\n\nSee a full example in [`./tracer-example`](./tracer-example).\n\n## Middleware\n\nOur recommendation is to use a middleware approach, where the trace ID is set once per request, causing only constant allocations, instead of allocations per span.\n\n### HTTP\n\nFor HTTP use the handler wrapper. Make sure it is called after an initial trace ID has been set on the context.\n\n```go\nimport (\n\t\"github.com/polarsignals/otel-profiling-go/otelhttpprofiling\"\n\t\"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp\"\n)\n\nfunc main() {\n\thandler := otelhttp.NewHandler(otelhttpprofiling.Handler(http.HandlerFunc(fibHandler)), \"fibHandler\")\n\n\t// ... actually serve handler\n}\n```\n\nSee a full example in [`./http-example`](./http-example).\n\n### gRPC\n\nFor gRPC use the gRPC middleware. Same as the HTTP middleware, ensure that it is after the otel interceptors to ensure a trace ID is already set on the context.\n\n```go\nimport (\n\tgrpc_middleware \"github.com/grpc-ecosystem/go-grpc-middleware\"\n)\n\nmain() {\n\totel.SetTracerProvider(initTracer())\n\n\tgrpcotelprof := otelgrpcprofiling.NewMiddleware()\n\tserver := grpc.NewServer(\n\t\tgrpc_middleware.WithUnaryServerChain(\n\t\t\totelgrpc.UnaryServerInterceptor(),\n\t\t\tgrpcotelprof.GrpcUnaryInterceptor,\n\t\t),\n\t\tgrpc_middleware.WithStreamServerChain(\n\t\t\totelgrpc.StreamServerInterceptor(),\n\t\t\tgrpcotelprof.GrpcStreamInterceptor,\n\t\t),\n\t)\n\n\t// ... register gRPC services, serve it, etc.\n}\n```\n\nSee a full example in [`./grpc-example`](./grpc-example).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarsignals%2Fotel-profiling-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolarsignals%2Fotel-profiling-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarsignals%2Fotel-profiling-go/lists"}