Skip to content

Add Telemetry to Application Name#3683

Open
aaronburtle wants to merge 10 commits into
mainfrom
dev/aaronburtle/Telemetry-in-app-name
Open

Add Telemetry to Application Name#3683
aaronburtle wants to merge 10 commits into
mainfrom
dev/aaronburtle/Telemetry-in-app-name

Conversation

@aaronburtle

Copy link
Copy Markdown
Contributor

Why make this change?

Closes #3216

DAB ships as an open-source container customers run anywhere, so we have little visibility into how it is configured or which features are used. This change encodes an anonymous usage fingerprint into the connection's Application Name, which the database side already records (e.g. sys.dm_exec_sessions.program_name), giving aggregate insight with no new endpoints, no network calls, and no per-customer data.

What is this change?

Embeds an anonymous, decodable usage-telemetry token into the Application Name of the connection strings DAB uses for SQL Server / Azure SQL, DWSQL, and PostgreSQL.

  • Format: dab_oss_<version>+<context>|<runtime>|<entity>+ a version plus three flag sections (Context = 4, Runtime = 20, Entity = 14). Values use 0/1 (off/on), M (missing section), X (not applicable at pool open), ? (not yet modeled).
  • Pooling-safe (Model A): only fields known when a pooled connection opens are encoded (the data-source engine as Source); per-request facets (protocol/object/role) are X so the connection-pool key, and therefore pool count, is unchanged.
  • Where it's injected: at config load (RuntimeConfigLoader) and on the hosted/late-config POST /configuration paths (RuntimeConfigProvider.Initialize). Embedding is idempotent (skips if the dab_oss_ marker is already present).
  • Multi-database: the global runtime + merged entity fingerprint is encoded at every pool (the token has no correlation id, so any single sampled connection reflects the whole deployment); Source still varies per pool.
  • Opt-out: DAB_TELEMETRY_APPNAME_OPT_OUT=1 reduces the value to version-only.
  • Hosted label: an existing DAB_APP_NAME_ENV value (e.g. dab_hosted) is preserved as a comma prefix and never suppresses the token.
  • CLI: new offline dab appname command to encode (--config) or decode (--decode) a token; -o/--output writes to a file.
  • Logging: the computed token (never the connection string) is logged at Debug via a bounded, drop-oldest LogBuffer flushed once the logger is available.
  • Scope: MySQL and Cosmos DB connection strings are left unchanged.
  • Design doc: docs/design/application-name-telemetry.md.

How was this tested?

  • Integration Tests
  • Unit Tests

Added encoder/decoder unit tests (token shape, every flag/section, Source + auth-provider maps, opt-out, host-label prefix, truncation-tolerant decode), connection-string injection tests for MSSQL/DWSQL/PostgreSQL (incl. user-supplied Application Name prefix) and no-op cases for MySQL/Cosmos, multi-database and hosted/late-config (/configuration + /configuration/v2) tests, an idempotency test, LogBuffer bound/flush tests, and CLI encode/decode/error/opt-out tests.

Sample Request(s)

Encode the token for a config (offline, no DB connection):

dab appname --config dab-config.json
# dab_oss_2.0.0+XXXX|110000M1M000MMMMMWMM|100?111001110?+

Decode a token back to a human-readable legend:

dab appname --decode "dab_oss_2.0.0+XXSX|110000M1M000MMMMMWMM|100?111001110?+"

Observe it on the SQL Server side:

SELECT program_name
FROM sys.dm_exec_sessions
WHERE program_name LIKE 'dab_oss%' OR program_name LIKE '%,dab_oss%';

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds anonymous, decodable usage telemetry by embedding a DAB-specific token into database connection strings’ Application Name for SQL Server/Azure SQL, DWSQL, and PostgreSQL, with an offline CLI encoder/decoder and buffered debug logging suitable for hosted/late-config and hot-reload scenarios.

Changes:

  • Introduces ApplicationNameTelemetry encoder/decoder and injects telemetry-bearing Application Name into MSSQL/DWSQL/PostgreSQL connection strings during config load and hosted/late-config initialization.
  • Makes telemetry embedding pool-safe/idempotent, adds bounded LogBuffer, and flushes buffered logs on hot reload and hosted initialization paths.
  • Adds new dab appname CLI command (encode/decode) plus extensive unit/E2E/integration test coverage for telemetry shape, injection behavior, multi-DB merge behavior, opt-out, and log buffering.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
src/Service.Tests/UnitTests/RuntimeConfigLoaderJsonDeserializerTests.cs Updates test to new MSSQL-specific Application Name injection helper.
src/Service.Tests/UnitTests/LogBufferTests.cs Adds unit tests for bounded buffering and flush/drain behavior.
src/Service.Tests/UnitTests/ApplicationNameTelemetryTests.cs Adds unit tests for telemetry encoding/decoding, opt-out, host label prefixing, and multi-DB live-vs-default encoding.
src/Service.Tests/Configuration/RuntimeConfigLoaderTests.cs Adds regression tests for multi-DB telemetry merge correctness, idempotency, and log buffer flushing.
src/Service.Tests/Configuration/ConfigurationTests.cs Updates/extends configuration tests for telemetry-bearing Application Name across MSSQL/Postgres/DWSQL and hosted/late-config scenarios.
src/Product/ProductInfo.cs Introduces a stable dab_oss_ marker constant and uses it to build the DAB user agent string.
src/Core/Configurations/RuntimeConfigProvider.cs Ensures telemetry is embedded and logs flushed during hosted/late-config initialization for all data sources.
src/Config/Telemetry/ApplicationNameTelemetry.cs Implements telemetry token encoding/decoding and environment-driven opt-out/label prefixing.
src/Config/RuntimeConfigLoader.cs Reworks post-parse connection string processing to support multi-DB, idempotent telemetry injection, and override behavior.
src/Config/ObjectModel/RuntimeConfig.cs Ensures child config loads skip Application Name injection so the merged/root config injects once globally.
src/Config/LogBuffer.cs Adds a max buffer size and drop-oldest behavior to prevent unbounded growth.
src/Config/FileSystemRuntimeConfigLoader.cs Flushes buffered logs on hot reload; uses base loader flushing via overridden logger property.
src/Config/DeserializationVariableReplacementSettings.cs Adds SkipApplicationNameInjection flag to coordinate multi-DB child/root injection behavior.
src/Cli/Program.cs Registers new appname command options.
src/Cli/Commands/AppNameOptions.cs Adds dab appname command (encode from config without validation; decode tolerant of truncation; optional file output).
src/Cli.Tests/EndToEndTests.cs Adds E2E coverage for appname encode/decode/output behaviors and updates Application Name assertions for telemetry.

Comment thread src/Config/Telemetry/ApplicationNameTelemetry.cs
Comment thread src/Config/LogBuffer.cs
@aaronburtle aaronburtle changed the title Dev/aaronburtle/telemetry in app name Add Telemetry to app-name Jun 26, 2026
@aaronburtle aaronburtle changed the title Add Telemetry to app-name Add Telemetry to Application Name Jun 26, 2026
@aaronburtle aaronburtle self-assigned this Jun 26, 2026
@aaronburtle aaronburtle added 2.1 telemetry feature requests/ bug reports related to telemetry labels Jun 26, 2026
@aaronburtle aaronburtle moved this from Todo to Review In Progress in Data API builder Jun 26, 2026
@aaronburtle aaronburtle added this to the June 2026 milestone Jun 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

2.1 telemetry feature requests/ bug reports related to telemetry

Projects

Status: Review In Progress

Development

Successfully merging this pull request may close these issues.

[Enh]: Telemetry in application_name

4 participants