You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
📖 **Load when**: Need reference for tracer configuration settings and environment variables
402
+
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`** — Human-readable descriptions and default values for all `DD_*` environment variables
403
+
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations.json`** — Machine-readable config metadata: product categorization, key aliases, and deprecations (consumed by source generators)
404
+
405
+
📖 **Load when**: Adding a new `DD_*` configuration key or modifying the configuration system
406
+
-**`docs/development/Configuration/AddingConfigurationKeys.md`** — Step-by-step guide for adding config keys: JSON/YAML definitions, source generators, aliases, telemetry normalization, and related analyzers
407
+
399
408
## Security & Configuration
400
409
401
410
- Do not commit secrets; prefer env vars (`DD_*`). `.env` should not contain credentials.
Copy file name to clipboardExpand all lines: docs/development/Configuration/AddingConfigurationKeys.md
+42-16Lines changed: 42 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,9 +22,9 @@ This guide explains how to add new configuration keys to the .NET Tracer. Config
22
22
23
23
Configuration keys in the .NET Tracer are defined in two source files:
24
24
25
-
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations.json`** - Defines the configuration keys, their
25
+
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations.json`** - Defines the configuration keys, their
26
26
environment variable names, and optional fallbacks.
27
-
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`** - Contains XML documentation for
27
+
-**`tracer/src/Datadog.Trace/Configuration/supported-configurations-docs.yaml`** - Contains XML documentation for
28
28
each key. We're using yaml here as it makes it easier for some of the long documentation summaries and formatting.
29
29
30
30
Two source generators read these files at build time:
@@ -40,22 +40,39 @@ Two source generators read these files at build time:
40
40
41
41
### 1. Add the Configuration Key Definition
42
42
43
-
Add your new configuration key to `tracer/src/Datadog.Trace/Configuration/supported-configurations.json`, specifying
44
-
an arbitrary version string (e.g. `"A"`, as shown below). and specifying the product if required. Any product name
45
-
is allowed, but try to reuse the existing ones (see [Common products](#common-products)) if it makes sense, as they will create another partial class, ie
43
+
Add your new configuration key to `tracer/src/Datadog.Trace/Configuration/supported-configurations.json`, specifying
44
+
an implementation string (`"A"` being the default one, as shown below) and specifying the product if required. Any product name
45
+
is allowed, but try to reuse the existing ones (see [Common products](#common-products)) if it makes sense, as they will create another partial class, ie
46
46
ConfigurationKeys.ProductName.cs. Without a product name, the keys will go in the main class, ConfigurationKeys.cs.
47
47
48
+
**Required fields (mandatory):**
49
+
-`implementation`: The implementation identifier
50
+
-`"A"` being the default one, it needs to match the registry implementation with the same type and default values
51
+
-`type`: The type of the configuration value (for example `string`, `boolean`, `int`, `decimal`)
52
+
-`default`: The default value applied by the tracer when the env var is not set. Use `null` if there is no default.
53
+
54
+
These fields are mandatory to keep the configuration registry complete and to ensure consistent behavior and documentation across products.
Configuration keys can have **aliases** that are checked in order of appearance when the primary key is not found. Add them to the `aliases` section in `supported-configurations.json`:
104
+
Configuration keys can have **aliases** that are checked in order of appearance when the primary key is not found. Add them to the `aliases` property of the configuration entry in `supported-configurations.json`:
0 commit comments