Telemetry

Request-lifecycle instrumentation (UsePortaTelemetry())

The bff.request span and the request/response-size, duration, and in-flight-count metrics cover the entire request pipeline, not just Porta endpoints. Because Porta has no always-on middleware, this is opt-in: register it as early as possible so it brackets everything.

var app = builder.Build();
app.UsePortaTelemetry();   // first, so it brackets the whole pipeline
app.UseRouting();
// ... auth, endpoints, etc.

The matched low-cardinality route template (e.g. /api/users/{id}) is read back from the resolved endpoint after the inner pipeline runs; requests that match no route are recorded under a single unmatched route series. The middleware is a no-op pass-through when EnableTelemetry is false.

Session-lifecycle metrics and the active-sessions gauge

bff.session.created / bff.session.invalidated are counters; bff.sessions.active is an up/down gauge incremented on create and decremented on each explicit termination. bff.session.invalidated carries a reason tag (logout, backchannel, admin, …). To keep the gauge balanced, cookie logout terminates the server-side session (in addition to clearing the cookie), and a terminate against an already-gone session never double-decrements. Note the gauge is still a lower bound on truly-active sessions: a session evicted purely by distributed-cache expiry (never explicitly terminated) is not counted as an invalidation, so the gauge can drift upward over long-lived deployments.

Reserved spans (declared but not yet emitted)

Two activity names are defined on PortaActivitySource but not yet started by any production path - queries against them return no data, and they are reserved for future use: bff.session (session-lifecycle metrics are emitted, but without a dedicated span) and bff.health_check.

Metric reference

All counters and histograms below are emitted under the b17s.Porta meter. Source of truth is PortaMetrics.cs - when in doubt, read the meter declarations there. The bff.request.*, bff.response.size, and bff.requests.active instruments require the opt-in UsePortaTelemetry() middleware; everything else is automatic when EnableTelemetry is true.

Counters

Histograms

Latency histograms use the OpenTelemetry http.server.request.duration-style buckets (0.5, 1, 2.5, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000 ms). Size histograms cover 256 B → 256 MiB so the MaxBackendResponseBytes (10 MiB) and MaxRawForwardResponseBytes (100 MiB) caps land in real buckets.

UpDownCounters

Span Hierarchy

Activity names are the fixed category strings (bff.transformation, bff.backend); the specific transformer/backend is carried on a tag, not baked into the name (see the note under Automatic Instrumentation). Porta's top-level endpoint span (bff.transformation here) is parented directly under the host's ambient ASP.NET Core request activity. The tags are shown in brackets below:

Incoming HTTP Request
└── ASP.NET Core Activity (auto)
    └── bff.transformation                [bff.transformation.strategy = EnrichedUserProfileTransformer]
        ├── bff.backend                   [bff.backend.service = api.internal.com]
        │   └── HTTP GET api.internal.com (auto)
        └── bff.backend                   [bff.backend.service = products.internal.com]
            └── HTTP GET products.internal.com (auto)

Trace Context Propagation

W3C Trace Context headers (traceparent, tracestate) are automatically propagated to all backend HTTP calls via AddHttpClientInstrumentation(). This enables end-to-end distributed tracing across services.

Configuration

builder.Services.AddPortaCore(options =>
{
    // Disable telemetry if needed (default: true)
    options.EnableTelemetry = false;
});

Tags and Attributes

Activity tags emitted by PortaActivitySource. Source of truth is PortaActivitySource.cs.

General

• bff.service.name
• bff.component - "transformer", "aggregator", "backend", etc.

HTTP

• http.method, http.url, http.status_code, http.route

Backend

• bff.backend.service - service hostname
• bff.backend.protocol - "http"
• bff.backend.endpoint, bff.backend.operation

Transformation

• bff.transformation.strategy - transformer class name
• bff.transformation.rule

Authentication

• bff.auth.provider - "SessionAuthProvider", "JwtBearerAuthProvider", "ReferenceTokenAuthProvider", etc.
• bff.auth.user_id
• bff.auth.token_type

Session

• bff.session.id
• bff.session.user_id

Health check

• bff.health.status, bff.health.backend_count

Errors

• error.type, error.message

Stack traces are intentionally not exposed as a tag (high cardinality + inner-exception messages frequently contain PII). Use Activity.AddException(ex) instead, which records the stack trace as event-scoped attributes per OpenTelemetry semantic conventions.

Exporting Traces

Traces are exported when OTEL_EXPORTER_OTLP_ENDPOINT is configured. The activity source is registered with OpenTelemetry in ServiceDefaults.

Example: Jaeger

# Start Jaeger
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Configure app
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Example: Aspire Dashboard

When running with .NET Aspire, traces are automatically exported to the Aspire dashboard.

Backend Call Logging

BackendCaller separates structured metadata logs from body logs so that production log sinks do not capture sensitive payloads (access tokens, refresh tokens, PII) by default.

Body logs are emitted at LogLevel.Trace, which is disabled by default in production. Enable Trace only for the b17s.Porta.Transformers.BackendCaller category in development or with operator approval - never enable it globally on a system that brokers tokens or PII.

Body length cap (PortaCore:MaxBodyLogLength)

To bound the blast radius of accidentally enabling Trace logs, body events 14015/14016/14017 are truncated to the first MaxBodyLogLength characters (default 512). Truncated entries get a … (truncated, N chars total) suffix so you can still see the full size in the meta log (14005/14006/14007).

GraphQL responses and any payload that may include access tokens, refresh tokens, or PII (e.g. me { ... } queries, OIDC userinfo) should keep the default cap. Set -1 only in isolated development environments where you have already accepted the risk.