.NET tracing installation

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.Hosting

OpenTelemetry.Extensions.Hosting wires OpenTelemetry into the host builder. For a plain console app using Sdk.CreateTracerProviderBuilder(), you can leave it out.

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 with phx_).

You can find your project token in Project settings.

Set up OpenTelemetry to export spans to PostHog over OTLP HTTP. The AddSource name must match the ActivitySource you 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, the Endpoint is used as-is, so include the full /i/v1/traces path. Don't use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, which appends its own /v1/traces.

.NET uses the built-in ActivitySource API for tracing. The source name must match the AddSource call 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 ...
}

StartActivity returns null when nothing is listening to the source, so use the null-conditional activity?. operator.

For ASP.NET Core on .NET 8 or later, use the PostHog request-context integration. Add PostHog to your existing host builder and put the middleware before your routes:

builder.AddPostHog();

var app = builder.Build();
app.UsePostHogRequestContext();

Configure tracing_headers for your backend hostname in the browser SDK. The middleware adds missing sessionId and posthogDistinctId tags to the active request Activity. The host-owned listener adds those tags to child activities when they start. Keep your existing OpenTelemetry provider, exporter, and sampling configuration.

Existing sessionId and posthogDistinctId tags take precedence. Set authenticated application identity with posthogDistinctId. Missing IDs stay absent. Tracing headers are untrusted analytics context. Use authenticated application identity for access decisions.

Activities that already started keep their tags after the request ends. New activities in detached work do not receive the ended request's IDs. Background jobs need their own context transfer. The core PostHog SDK does not provide a native span API or a trace exporter.

Once everything is configured, confirm spans are reaching PostHog:

1. Run your application and trigger the instrumented code
2. Open the PostHog Tracing interface
3. Confirm your spans and traces appear