FF.Telemetry.Sdk (0.2.0)
Installation
dotnet nuget add source --name flowprime --username your_username --password your_token https://git.fastflow.tech/api/packages/flowprime/nuget/index.jsondotnet add package --source flowprime --version 0.2.0 FF.Telemetry.SdkAbout 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
REDACTEDwhen 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 asaccountKey.randomToken,key:tokenor 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.
SecretPathPrefixesnames 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:
-
the host starts with
{tenant}.- the platform's org subdomains, no configuration needed; -
Browser.TenantHostsholds 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.aiwithTelemetry__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-Slugor?tenant=) loses it, counted asff_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.