Diagnostics SDK
Configuration reference
Every environment variable the Diagnostics SDK reads, with defaults and activation rules.
Configuration reference
The SDK is configured exclusively via environment variables. There is no
code-based or file-based configuration. If TICKETMAN_DIAG_ENDPOINT is not set, or
is not a valid http(s) URL, the SDK is fully inert.
Boolean values: true, 1 or yes (case-insensitive) enable; anything else
disables. Invalid values fall back to the default and are noted in the self-log.
Core
| Variable | Default | Description |
|---|---|---|
TICKETMAN_DIAG_ENDPOINT | unset (SDK inert) | Full HTTPS URL of the TicketMan ingest endpoint. |
TICKETMAN_DIAG_API_KEY | empty | API key, sent as X-TicketMan-Key. |
TICKETMAN_DIAG_ENVIRONMENT | DOTNET_ENVIRONMENT or ASPNETCORE_ENVIRONMENT, else Production | Environment name reported with the incident. |
TICKETMAN_DIAG_APP_NAME | entry assembly name | Application name. |
TICKETMAN_DIAG_APP_VERSION | assembly informational version | Application version. |
TICKETMAN_DIAG_BUILD_ID | empty | CI build identifier. |
TICKETMAN_DIAG_GIT_COMMIT | commit suffix of the version | Git commit hash. |
TICKETMAN_DIAG_TIMEOUT_SECONDS | 10 | HTTP timeout per send attempt. |
TICKETMAN_DIAG_DEBUG | false | Self-log internal decisions and errors to stderr and Trace. |
Capture options
| Variable | Default | Description |
|---|---|---|
TICKETMAN_DIAG_CAPTURE_USER | false | Opt-in: include user id, username, tenant and roles from claims. |
TICKETMAN_DIAG_CAPTURE_REQUEST_BODY | false | Opt-in: include the masked, size-capped HTTP request body. |
TICKETMAN_DIAG_MAX_REQUEST_BODY_BYTES | 16384 | Request body cap; longer bodies are truncated and flagged. |
TICKETMAN_DIAG_HTTP_STATUS_RANGES | 500-599 | Status codes or ranges that trigger a report with no exception, e.g. 500-599,429. |
TICKETMAN_DIAG_ENABLE_DUMPS | false | Capture a minidump (stacks and modules, no full heap) on fatal crashes. .NET only. |
TICKETMAN_DIAG_MAX_ATTACHMENT_SIZE_MB | 10 | Attachments larger than this are dropped. |
TICKETMAN_DIAG_BREADCRUMB_BUFFER_SIZE | 100 | Ring-buffer size for log breadcrumbs. 0 disables breadcrumbs. |
TICKETMAN_DIAG_CAPTURE_LOG_LEVEL | Critical (.NET) / fatal (Node) | Minimum log level at which a logged exception is captured as an error report; None/none disables. Set it to Error/error to capture exceptions your code catches and logs, with no code changes. |
Delivery and limits
| Variable | Default | Description |
|---|---|---|
TICKETMAN_DIAG_SPOOL_DIR | <temp>/ticketman-diagnostics/<app-name> | Local spool directory for pending reports. Must be writable. |
TICKETMAN_DIAG_SPOOL_MAX_MB | 50 | Spool size cap; oldest reports are evicted first. |
TICKETMAN_DIAG_RATE_LIMIT | 10/5m | Per-fingerprint client-side limit, N/window with s, m or h. |
Masking and claims
| Variable | Default | Description |
|---|---|---|
TICKETMAN_DIAG_MASK_EXTRA_KEYS | empty | Extra key names the masker treats as secrets. |
TICKETMAN_DIAG_USER_CLAIM_ID | sub, oid, nameidentifier | Claim type for the user id. |
TICKETMAN_DIAG_USER_CLAIM_NAME | preferred_username, name | Claim type for the username. |
TICKETMAN_DIAG_USER_CLAIM_TENANT | tid | Claim type for the tenant. |
TICKETMAN_DIAG_USER_CLAIM_ROLES | roles, role | Claim type for roles. |
Per-SDK differences
The same variables drive every SDK; only the derived defaults and a few platform-bound options differ:
- .NET: environment defaults from
DOTNET_ENVIRONMENT/ASPNETCORE_ENVIRONMENT; app name and version from assembly metadata;CAPTURE_LOG_LEVELtakesILoggerlevel names (defaultCritical); user identity comes from claims via theUSER_CLAIM_*variables. - Node.js: environment defaults from
NODE_ENV; app name and version from the nearestpackage.json;CAPTURE_LOG_LEVELtakestrace|debug|info|warn|error|fatal|none(defaultfatal); user identity comes fromreq.user(theUSER_CLAIM_*variables do not apply);TICKETMAN_DIAG_ENABLE_DUMPSis not implemented — minidumps are .NET-only.
Activation rules
- If
TICKETMAN_DIAG_ENDPOINTis unset or invalid, everything else is ignored and the SDK is inert. - Explicit
TICKETMAN_DIAG_*values always win over derived defaults. - Masking cannot be disabled.
MASK_EXTRA_KEYScan only add to the built-in list. - Server throttle hints (pause or sample rate) override client behavior until replaced.