FlowPrime

FlowPrime SDKs and API clients

FF.Telemetry.Sdk (0.2.0)

Published 2026-11-17 16:29:04 +13:00 by ci-platform

Installation

dotnet nuget add source --name flowprime --username your_username --password your_token https://git.fastflow.tech/api/packages/flowprime/nuget/index.json
dotnet add package --source flowprime --version 0.2.0 FF.Telemetry.Sdk

About this package

Logs, traces, metrics and browser reports in the FlowPrime telemetry contract, for FastFlowTech services

FF.Telemetry.Sdk

The FlowPrime telemetry contract for a FastFlowTech service: what a service emits so that a customer's onboarding or application failure can be diagnosed from Grafana, without a password, a token or a message body ever reaching a log, a span or a report.

Opt-in. Nothing changes for a service until it calls the three extension methods below.

Wire it

builder.AddFFTelemetry(o => o.ServiceName = "mail");   // before builder.Build()

app.UseForwardedHeaders(...);
app.UseFFTelemetry();                                   // right after forwarded headers
...
app.MapFFTelemetryEndpoints();                          // /metrics, /_telemetry/report, /_telemetry/client.js

A service with tenant resolution lists /metrics and /_telemetry/ as platform paths (they resolve no tenant and are anonymous).

Order matters: forwarded headers, then UseFFTelemetry, then whatever resolves the tenant into HttpContext.Items[TenantItemKey] (default ResolvedOrgSlug), then the endpoints. The report sink reads the tenant at the endpoint, so a resolver that runs after it binds nothing.

What it emits

Logs. One flat JSON object per line on stdout, parsed by the platform's Alloy pipeline. Every line carries ts (UTC), level, logger, msg, service, version, env, and when present trace_id, span_id, request_id, journey_id, tenant, edge_ray. Named template properties become snake_case fields. event_class says what a line is:

event_class written by kept
journey FFJourney.Event(...): a named onboarding step and its outcome 90 days
request the middleware, once per non-excluded request: method, sanitized path, route, status, duration, media type, disposition type, redirect origin and path 30 days
browser the report sink: CSP violations, script errors, failed fetches, lifecycle, product-ready 30 days
(none) ordinary application logging 30 days

EF Core's SQL echo and the ASP.NET request noise are filtered to Warning unless the host configuration names those categories itself.

Traces. ASP.NET Core server spans and HttpClient client spans, exported over OTLP/HTTP to the in-cluster gateway (Telemetry:Otlp:Endpoint, default http://otel-gateway.observability.svc:4318) when the process runs in a Kubernetes pod outside Development. The gateway derives the tenant from the pod's namespace; the service sends no credential and no tenant. Every URL on a span is sanitized before export: query values become REDACTED (names stay), userinfo and fragments are dropped, secret-shaped path segments are replaced (see "Secrets in a route"). The server span also carries ff.request_id, ff.journey_id, ff.tenant, ff.edge.ray (the CF-Ray, the join key to the Traefik access log) and the bounded response metadata.

Hand-made spans use FFMessagingTelemetry.Source. For a message bus: FFMessagingTelemetry.Inject((k, v) => headers[k] = v) on publish and using var act = FFMessagingTelemetry.StartConsumer("nats", subject, k => headers[k]) on consume: the consumer opens its own trace LINKED to the producer's span, so a request trace stays bounded and a redelivery stands on its own.

Metrics. Prometheus text at /metrics for the namespace ServiceMonitor: ASP.NET Core, HttpClient and runtime instruments, plus ff_journey_events_total{event,outcome} and ff_browser_reports_total{type,outcome}. A scrape that arrives through the ingress (forwarding headers present) is answered 404.

Journey events. FFJourney.Event(logger, "login", FFOutcome.Ok, "password", ("user_id", id)). Names are stable snake_case steps, outcomes are the closed set in FFOutcome, reasons are short constants. Tags are tenant-safe identifiers, never an e-mail, a token or a body.

Browser reporting. Add to the hosted layout:

<meta name="ff-telemetry" data-page-ref="@Context.TraceIdentifier">
<script src="/_telemetry/client.js" defer></script>

and report-uri /_telemetry/report in the CSP. report-uri only: do not send report-to or a Reporting-Endpoints header. Measured in Chromium on staging, a policy that also names report-to makes the browser ignore report-uri and queue the Reporting API delivery on a delay, so a violation on a page the person leaves within a minute never arrives; report-uri alone posts at once from every current browser. (The sink still accepts the application/reports+json shape, it is just not what the header should ask for.) Reports are untrusted input: size and count bounded, rate limited per client address, event types a closed set, URLs and stacks sanitized twice, only the page's own origin accepted, and the tenant and journey taken from the server's own request context, never the body (see "The tenant on a browser report"). A page marks its arrival with window.ffTelemetry.ready("dashboard") or a <meta name="ff-telemetry-ready" content="dashboard">.

Secrets in a route

Anywhere the SDK writes a path - the request line's msg, path and redirect_path, the span's url.path / url.full / http.target / http.response.redirect_path, a browser line's page, target, document, blocked, message and stack - one rule applies:

  • By shape, always on. A path segment is percent-decoded (up to three rounds) and replaced with REDACTED when it holds a run of 32 or more url-safe characters (A-Z a-z 0-9 _ - ~ = +). The run may sit anywhere in the segment, so a compound secret such as accountKey.randomToken, key:token or a JWT is replaced whole, with its separator encoded or not. A GUID is kept. A bare ?<token> query name is judged the same way; query values are always replaced.

  • By route, when you say so. SecretPathPrefixes names route prefixes whose NEXT segment is a secret whatever its length:

    builder.AddFFTelemetry(o =>
    {
        o.ServiceName = "fotoprime";
        o.SecretPathPrefixes.Add("/p/");        // /p/{token}/zip, /p/{token}/i/{n}
        o.SecretPathPrefixes.Add("/assinar/");  // /assinar/{token}
    });
    

    or Telemetry__SecretPathPrefixes__0=/p/. Literal prefixes, compared without case, 64 at most; /, a wildcard or a query stops the service at startup. Name every route you know carries a secret even when its token is long today: the shape rule is the net, the prefix is the statement.

Only what is WRITTEN changes. The URL the product serves, the Location header the browser receives and the route template (route, http.route, which carry {token}, never its value) are untouched.

What this does not cover: an application's own log message. The formatter truncates msg and the named properties, it does not search them, so log.LogInformation("link {Url}", url) with a secret in url still logs it, and so does a third-party library that prints a token. Pass FFSanitize.Url(url) / FFSanitize.Path(path) / FFSanitize.Text(text, max) yourself, or lower that category's level.

The tenant on a browser report

A report is an anonymous POST, so the sink keeps a tenant on its lines only when the request's HOST proves it. Two proofs exist:

  1. the host starts with {tenant}. - the platform's org subdomains, no configuration needed;

  2. Browser.TenantHosts holds an entry naming exactly this host AND exactly that tenant - for a product served on its own host:

    o.Browser.TenantHosts.Add(new("fotoprime.fastflowtech.ai", "fotoprime-staging-validation"));
    

    or Telemetry__Browser__TenantHosts__0__Host=fotoprime.fastflowtech.ai with Telemetry__Browser__TenantHosts__0__Tenant=fotoprime-staging-validation.

A binding CONFIRMS, it never assigns. The tenant is still the one your own server-side resolution put in Items[TenantItemKey] for this request; the binding only says that, on this host, that value is believable. So:

  • a bound host whose resolution produced no tenant writes no tenant;
  • a bound host whose resolution produced a DIFFERENT tenant (a resolver that believed X-Org-Slug or ?tenant=) loses it, counted as ff_browser_reports_total{outcome="tenant_unbound"};
  • an unbound host loses any tenant, even the right one;
  • nothing in the report body is ever read as a tenant.

Entries are exact DNS host names compared without case: no scheme, port, path or wildcard, and a blank or malformed entry stops the service at startup rather than quietly widening the boundary. A host that serves several tenants gets one entry per tenant. The list comes from the application's configuration, so it is as trustworthy as that is: the Host header is only as good as the ingress in front of the pod, which is why UseForwardedHeaders must be limited to the platform's proxies, as it is for every other use of the host. A product whose hosts live in a database rather than in configuration is not covered by this list yet.

Configuration (Telemetry section)

Everything has a default; the launch profile is full capture.

Telemetry__Enabled=true
Telemetry__Otlp__Enabled=            (empty: in-cluster and not Development)
Telemetry__Otlp__Endpoint=http://otel-gateway.observability.svc:4318
Telemetry__Traces__SampleRatio=1.0   (parent-based: a sampled parent is always kept)
Telemetry__Logs__Json=true
Telemetry__Logs__LogRequests=true
Telemetry__Metrics__Enabled=true
Telemetry__Journey__Enabled=true
Telemetry__Browser__Enabled=true
Telemetry__Browser__RateLimitPerMinute=60
Telemetry__SecretPathPrefixes__0=            (none by default)
Telemetry__Browser__TenantHosts__0__Host=    (none by default)
Telemetry__Browser__TenantHosts__0__Tenant=

What it never does

No request or response bodies, no headers other than the ones named above, no query values, no cookies, no e-mail addresses from the SDK's own lines, no session replay, no form content. Collector loss never blocks a request: the exporter is a bounded batch queue that drops the oldest span.

0.2.0: compound route secrets ("accountKey.randomToken", percent-encoded separators, JWTs) are redacted whole everywhere a path is written; Telemetry:SecretPathPrefixes always redacts the segment after a named route prefix; Telemetry:Browser:TenantHosts binds a product's own host to its tenant so browser reports keep the server-resolved tenant there, while headers, query values and report bodies still bind nothing. CSP reporting is documented as report-uri only. No breaking change: a 0.1.x consumer upgrades without code changes.

Dependencies

ID Version Target Framework
OpenTelemetry 1.19.0 net10.0
OpenTelemetry.Exporter.OpenTelemetryProtocol 1.19.0 net10.0
OpenTelemetry.Exporter.Prometheus.AspNetCore 1.19.0-beta.1 net10.0
OpenTelemetry.Extensions.Hosting 1.19.0 net10.0
OpenTelemetry.Instrumentation.AspNetCore 1.19.0 net10.0
OpenTelemetry.Instrumentation.Http 1.19.0 net10.0
OpenTelemetry.Instrumentation.Runtime 1.19.0 net10.0
Details
NuGet
2026-11-17 16:29:04 +13:00
4
FastFlowTech
45 KiB
Assets (2)
Versions (1) View all
0.2.0 2026-11-17