references/dotnet.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
.NET tracing installation
Canonical URL: https://posthog.com/docs/distributed-tracing/installation/dotnet
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install OpenTelemetry packages
- Get your project token
- Configure the SDK
- Create spans
- Test your setup
- Next steps
-
1
Install OpenTelemetry packages
Required
For the complete SDK reference, see the OpenTelemetry .NET docs.
dotnet add package OpenTelemetry dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol dotnet add package OpenTelemetry.Extensions.HostingOpenTelemetry.Extensions.Hostingwires OpenTelemetry into the host builder. For a plain console app usingSdk.CreateTracerProviderBuilder(), you can leave it out. -
2
Get your project token
Required
You'll need your PostHog project token to authenticate trace requests. This is the same token you use for capturing events with the PostHog SDK.
Important: Use your project token which starts with
phc_. Do not use a personal API key (which starts withphx_).You can find your project token in Project settings.
-
3
Configure the SDK
Required
Set up OpenTelemetry to export spans to PostHog over OTLP HTTP. The
AddSourcename must match theActivitySourceyou create in the next step.using OpenTelemetry; using OpenTelemetry.Exporter; using OpenTelemetry.Resources; using OpenTelemetry.Trace; var builder = WebApplication.CreateBuilder(args); builder.Services.AddOpenTelemetry() .ConfigureResource(resource => resource.AddService("my-service")) .WithTracing(tracing => tracing .AddSource("MyCompany.MyApp") .AddOtlpExporter(options => { options.Endpoint = new Uri("https://us.i.posthog.com/i/v1/traces"); options.Protocol = OtlpExportProtocol.HttpProtobuf; options.Headers = "Authorization=Bearer <ph_project_token>"; }));Alternatively, configure the exporter with environment variables and call
AddOtlpExporter()with no arguments:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.i.posthog.com/i/v1/traces" OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <ph_project_token>" OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf" OTEL_SERVICE_NAME="my-service"Note: With
HttpProtobuf, theEndpointis used as-is, so include the full/i/v1/tracespath. Don't use the baseOTEL_EXPORTER_OTLP_ENDPOINTvariable, which appends its own/v1/traces. -
4
Create spans
Required
.NET uses the built-in
ActivitySourceAPI for tracing. The source name must match theAddSourcecall above.using System.Diagnostics; static readonly ActivitySource MyActivitySource = new("MyCompany.MyApp"); public void ProcessOrder(string orderId) { using Activity? activity = MyActivitySource.StartActivity("process-order"); activity?.SetTag("order.id", orderId); // ... do work ... }StartActivityreturnsnullwhen nothing is listening to the source, so use the null-conditionalactivity?.operator. -
5
Test your setup
Recommended
Once everything is configured, confirm spans are reaching PostHog:
- Run your application and trigger the instrumented code
- Open the PostHog Tracing interface
- Confirm your spans and traces appear
-
Next steps
Checkpoint
What you can do with your traces
| Action | Description | | --- | --- | | Why you need distributed tracing | What a trace shows you that nothing else does | | Explore traces | Read a trace as a waterfall to see where time goes | | Filter spans | Narrow down by service, status, duration, and attributes | | Propagate context | Pass trace context across services so spans join the same trace |