Add Docs on How to Add a Configuration #9835
Merged
+63
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Hi! 👋 Thanks for your pull request! 🎉 To help us review it, please make sure to:
If you need help, please check our contributing guidelines. |
mhlidd
added
type: documentation
tag: no release notes
|
🎯 Code Coverage 🔗 Commit SHA: 86f5570 | Docs | Was this helpful? Give us feedback! |
BenchmarksStartupParameters
See matching parameters
SummaryFound 0 performance improvements and 1 performance regressions! Performance is the same for 52 metrics, 12 unstable metrics.
Startup time reports for insecure-bankgantt
title insecure-bank - global startup overhead: candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section tracing
Agent [baseline] (1.028 s) : 0, 1028218
Total [baseline] (8.676 s) : 0, 8676028
Agent [candidate] (1.018 s) : 0, 1017992
Total [candidate] (8.658 s) : 0, 8658240
section iast
Agent [baseline] (1.17 s) : 0, 1169949
Total [baseline] (9.333 s) : 0, 9332759
Agent [candidate] (1.153 s) : 0, 1153083
Total [candidate] (9.277 s) : 0, 9277232
gantt
title insecure-bank - break down per module: candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section tracing
crashtracking [baseline] (1.46 ms) : 0, 1460
crashtracking [candidate] (1.457 ms) : 0, 1457
BytebuddyAgent [baseline] (700.942 ms) : 0, 700942
BytebuddyAgent [candidate] (693.826 ms) : 0, 693826
GlobalTracer [baseline] (244.413 ms) : 0, 244413
GlobalTracer [candidate] (243.181 ms) : 0, 243181
AppSec [baseline] (32.229 ms) : 0, 32229
AppSec [candidate] (32.173 ms) : 0, 32173
Debugger [baseline] (6.386 ms) : 0, 6386
Debugger [candidate] (6.284 ms) : 0, 6284
Remote Config [baseline] (677.059 µs) : 0, 677
Remote Config [candidate] (668.028 µs) : 0, 668
Telemetry [baseline] (15.234 ms) : 0, 15234
Telemetry [candidate] (9.238 ms) : 0, 9238
Flare Poller [baseline] (5.716 ms) : 0, 5716
Flare Poller [candidate] (10.139 ms) : 0, 10139
section iast
crashtracking [baseline] (1.481 ms) : 0, 1481
crashtracking [candidate] (1.479 ms) : 0, 1479
BytebuddyAgent [baseline] (830.569 ms) : 0, 830569
BytebuddyAgent [candidate] (816.068 ms) : 0, 816068
GlobalTracer [baseline] (235.216 ms) : 0, 235216
GlobalTracer [candidate] (231.873 ms) : 0, 231873
AppSec [baseline] (28.946 ms) : 0, 28946
AppSec [candidate] (35.544 ms) : 0, 35544
Debugger [baseline] (6.095 ms) : 0, 6095
Debugger [candidate] (6.168 ms) : 0, 6168
Remote Config [baseline] (593.481 µs) : 0, 593
Remote Config [candidate] (597.337 µs) : 0, 597
Telemetry [baseline] (8.373 ms) : 0, 8373
Telemetry [candidate] (8.722 ms) : 0, 8722
Flare Poller [baseline] (4.083 ms) : 0, 4083
Flare Poller [candidate] (4.34 ms) : 0, 4340
IAST [baseline] (33.103 ms) : 0, 33103
IAST [candidate] (27.022 ms) : 0, 27022
Startup time reports for petclinicgantt
title petclinic - global startup overhead: candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section tracing
Agent [baseline] (1.029 s) : 0, 1028750
Total [baseline] (10.782 s) : 0, 10781677
Agent [candidate] (1.017 s) : 0, 1016535
Total [candidate] (10.668 s) : 0, 10667914
section appsec
Agent [baseline] (1.203 s) : 0, 1203331
Total [baseline] (10.842 s) : 0, 10842279
Agent [candidate] (1.202 s) : 0, 1202057
Total [candidate] (10.86 s) : 0, 10859730
section iast
Agent [baseline] (1.177 s) : 0, 1177428
Total [baseline] (11.197 s) : 0, 11197113
Agent [candidate] (1.155 s) : 0, 1154882
Total [candidate] (11.178 s) : 0, 11177630
section profiling
Agent [baseline] (1.174 s) : 0, 1173867
Total [baseline] (10.858 s) : 0, 10857642
Agent [candidate] (1.164 s) : 0, 1163701
Total [candidate] (10.859 s) : 0, 10859457
gantt
title petclinic - break down per module: candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section tracing
crashtracking [baseline] (1.46 ms) : 0, 1460
crashtracking [candidate] (1.441 ms) : 0, 1441
BytebuddyAgent [baseline] (701.624 ms) : 0, 701624
BytebuddyAgent [candidate] (691.437 ms) : 0, 691437
GlobalTracer [baseline] (244.867 ms) : 0, 244867
GlobalTracer [candidate] (242.286 ms) : 0, 242286
AppSec [baseline] (32.017 ms) : 0, 32017
AppSec [candidate] (32.077 ms) : 0, 32077
Debugger [baseline] (6.376 ms) : 0, 6376
Debugger [candidate] (6.282 ms) : 0, 6282
Remote Config [baseline] (675.81 µs) : 0, 676
Remote Config [candidate] (676.255 µs) : 0, 676
Telemetry [baseline] (14.202 ms) : 0, 14202
Telemetry [candidate] (9.312 ms) : 0, 9312
Flare Poller [baseline] (6.345 ms) : 0, 6345
Flare Poller [candidate] (12.0 ms) : 0, 12000
section appsec
crashtracking [baseline] (1.464 ms) : 0, 1464
crashtracking [candidate] (1.467 ms) : 0, 1467
BytebuddyAgent [baseline] (726.949 ms) : 0, 726949
BytebuddyAgent [candidate] (723.326 ms) : 0, 723326
GlobalTracer [baseline] (235.55 ms) : 0, 235550
GlobalTracer [candidate] (236.353 ms) : 0, 236353
AppSec [baseline] (174.35 ms) : 0, 174350
AppSec [candidate] (173.679 ms) : 0, 173679
Debugger [baseline] (5.963 ms) : 0, 5963
Debugger [candidate] (6.164 ms) : 0, 6164
Remote Config [baseline] (628.355 µs) : 0, 628
Remote Config [candidate] (642.625 µs) : 0, 643
Telemetry [baseline] (8.391 ms) : 0, 8391
Telemetry [candidate] (10.151 ms) : 0, 10151
Flare Poller [baseline] (3.882 ms) : 0, 3882
Flare Poller [candidate] (3.952 ms) : 0, 3952
IAST [baseline] (24.942 ms) : 0, 24942
IAST [candidate] (25.133 ms) : 0, 25133
section iast
crashtracking [baseline] (1.484 ms) : 0, 1484
crashtracking [candidate] (1.447 ms) : 0, 1447
BytebuddyAgent [baseline] (836.337 ms) : 0, 836337
BytebuddyAgent [candidate] (817.437 ms) : 0, 817437
GlobalTracer [baseline] (236.137 ms) : 0, 236137
GlobalTracer [candidate] (232.113 ms) : 0, 232113
AppSec [baseline] (29.932 ms) : 0, 29932
AppSec [candidate] (35.44 ms) : 0, 35440
Debugger [baseline] (6.228 ms) : 0, 6228
Debugger [candidate] (6.227 ms) : 0, 6227
Remote Config [baseline] (612.149 µs) : 0, 612
Remote Config [candidate] (614.158 µs) : 0, 614
Telemetry [baseline] (8.644 ms) : 0, 8644
Telemetry [candidate] (8.807 ms) : 0, 8807
Flare Poller [baseline] (4.162 ms) : 0, 4162
Flare Poller [candidate] (4.341 ms) : 0, 4341
IAST [baseline] (32.238 ms) : 0, 32238
IAST [candidate] (27.013 ms) : 0, 27013
section profiling
ProfilingAgent [baseline] (109.462 ms) : 0, 109462
ProfilingAgent [candidate] (109.717 ms) : 0, 109717
crashtracking [baseline] (1.467 ms) : 0, 1467
crashtracking [candidate] (1.46 ms) : 0, 1460
BytebuddyAgent [baseline] (727.165 ms) : 0, 727165
BytebuddyAgent [candidate] (720.563 ms) : 0, 720563
GlobalTracer [baseline] (220.535 ms) : 0, 220535
GlobalTracer [candidate] (218.555 ms) : 0, 218555
AppSec [baseline] (32.303 ms) : 0, 32303
AppSec [candidate] (32.251 ms) : 0, 32251
Debugger [baseline] (12.204 ms) : 0, 12204
Debugger [candidate] (6.618 ms) : 0, 6618
Remote Config [baseline] (1.446 ms) : 0, 1446
Remote Config [candidate] (690.902 µs) : 0, 691
Telemetry [baseline] (9.677 ms) : 0, 9677
Telemetry [candidate] (15.894 ms) : 0, 15894
Flare Poller [baseline] (4.222 ms) : 0, 4222
Flare Poller [candidate] (4.134 ms) : 0, 4134
Profiling [baseline] (110.099 ms) : 0, 110099
Profiling [candidate] (110.416 ms) : 0, 110416
LoadParameters
See matching parameters
SummaryFound 0 performance improvements and 3 performance regressions! Performance is the same for 9 metrics, 12 unstable metrics.
Request duration reports for insecure-bankgantt
title insecure-bank - request duration [CI 0.99] : candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section baseline
no_agent (4.313 ms) : 4261, 4365
. : milestone, 4313,
iast (9.547 ms) : 9390, 9703
. : milestone, 9547,
iast_FULL (14.316 ms) : 14032, 14601
. : milestone, 14316,
iast_GLOBAL (10.812 ms) : 10619, 11005
. : milestone, 10812,
profiling (8.706 ms) : 8562, 8850
. : milestone, 8706,
tracing (7.802 ms) : 7686, 7919
. : milestone, 7802,
section candidate
no_agent (4.36 ms) : 4312, 4408
. : milestone, 4360,
iast (9.997 ms) : 9829, 10165
. : milestone, 9997,
iast_FULL (13.921 ms) : 13648, 14195
. : milestone, 13921,
iast_GLOBAL (11.178 ms) : 10974, 11381
. : milestone, 11178,
profiling (8.752 ms) : 8608, 8897
. : milestone, 8752,
tracing (8.217 ms) : 8091, 8342
. : milestone, 8217,
Request duration reports for petclinicgantt
title petclinic - request duration [CI 0.99] : candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section baseline
no_agent (37.148 ms) : 36853, 37443
. : milestone, 37148,
appsec (48.866 ms) : 48437, 49296
. : milestone, 48866,
code_origins (43.548 ms) : 43164, 43933
. : milestone, 43548,
iast (44.365 ms) : 43987, 44742
. : milestone, 44365,
profiling (50.307 ms) : 49821, 50793
. : milestone, 50307,
tracing (42.561 ms) : 42205, 42918
. : milestone, 42561,
section candidate
no_agent (37.426 ms) : 37128, 37723
. : milestone, 37426,
appsec (50.244 ms) : 49797, 50692
. : milestone, 50244,
code_origins (44.375 ms) : 43989, 44762
. : milestone, 44375,
iast (43.255 ms) : 42885, 43624
. : milestone, 43255,
profiling (50.638 ms) : 50148, 51128
. : milestone, 50638,
tracing (44.423 ms) : 44052, 44793
. : milestone, 44423,
DacapoParameters
See matching parameters
SummaryFound 0 performance improvements and 0 performance regressions! Performance is the same for 11 metrics, 1 unstable metrics. Execution time for biojavagantt
title biojava - execution time [CI 0.99] : candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section baseline
no_agent (15.019 s) : 15019000, 15019000
. : milestone, 15019000,
appsec (14.709 s) : 14709000, 14709000
. : milestone, 14709000,
iast (18.555 s) : 18555000, 18555000
. : milestone, 18555000,
iast_GLOBAL (18.483 s) : 18483000, 18483000
. : milestone, 18483000,
profiling (15.29 s) : 15290000, 15290000
. : milestone, 15290000,
tracing (15.183 s) : 15183000, 15183000
. : milestone, 15183000,
section candidate
no_agent (15.443 s) : 15443000, 15443000
. : milestone, 15443000,
appsec (14.746 s) : 14746000, 14746000
. : milestone, 14746000,
iast (18.69 s) : 18690000, 18690000
. : milestone, 18690000,
iast_GLOBAL (18.103 s) : 18103000, 18103000
. : milestone, 18103000,
profiling (15.727 s) : 15727000, 15727000
. : milestone, 15727000,
tracing (14.892 s) : 14892000, 14892000
. : milestone, 14892000,
Execution time for tomcatgantt
title tomcat - execution time [CI 0.99] : candidate=1.55.0-SNAPSHOT~86f557069d, baseline=1.55.0-SNAPSHOT~45b8e1524b
dateFormat X
axisFormat %s
section baseline
no_agent (1.479 ms) : 1467, 1490
. : milestone, 1479,
appsec (3.715 ms) : 3498, 3933
. : milestone, 3715,
iast (2.215 ms) : 2151, 2279
. : milestone, 2215,
iast_GLOBAL (2.257 ms) : 2193, 2321
. : milestone, 2257,
profiling (2.045 ms) : 1994, 2096
. : milestone, 2045,
tracing (2.025 ms) : 1976, 2074
. : milestone, 2025,
section candidate
no_agent (1.472 ms) : 1461, 1484
. : milestone, 1472,
appsec (3.682 ms) : 3465, 3899
. : milestone, 3682,
iast (2.213 ms) : 2150, 2277
. : milestone, 2213,
iast_GLOBAL (2.246 ms) : 2182, 2311
. : milestone, 2246,
profiling (2.06 ms) : 2008, 2112
. : milestone, 2060,
tracing (2.023 ms) : 1973, 2074
. : milestone, 2023,
|
docs/add_new_configurations.md
Outdated
| Configurations are separated into different files based on the product they are related to. e.g. `CiVisiblity` related configurations live in `CiVisibilityConfig`, `Tracer` related in `TracerConfig`, etc. | ||
| Default values for configurations live in `ConfigDefaults.java`. | ||
|
|
||
| Configuration values are read in `Config.java`, which utilizes helper methods in `ConfigProvider.java` to fetch the final value for a configuration after searching through all Configuration Sources and determining the final value based on Source priority. |
There was a problem hiding this comment.
🎯 suggestion: It could be nice to show a list of the various configuration sources and what their purpose are. Typically, the one from CI Vis is not trivial.
There was a problem hiding this comment.
@mtoffl01 and I discussed that we wait to add documentation for Sources until Stable/Declarative/Hands-Off Config has a finalized term to be used publicly.
Documentation about sources will likely be a new README that is linked from this page.
There was a problem hiding this comment.
I think it's alright to document this now in dd-trace-java docs; in our conversations, I meant that public docs (docs.datadoghq.com) must wait.
The name for this file-based config stuff is definitely, officially Declarative Config 😁 .
Happy to help craft the sources doc if need be.
There was a problem hiding this comment.
What could actually be good is if we mention the sources here, and link to the public docs with more info. I don't think devs generally need to be super concerned about the sources when adding new configurations, but a link could always be good to provide more info. WDYT?
PerfectSlayer
changed the title
PerfectSlayer
changed the title
mtoffl01
approved these changes
Oct 23, 2025
docs/add_new_configurations.md
Outdated
| Configurations are separated into different files based on the product they are related to. e.g. `CiVisiblity` related configurations live in `CiVisibilityConfig`, `Tracer` related in `TracerConfig`, etc. | ||
| Default values for configurations live in `ConfigDefaults.java`. | ||
|
|
||
| Configuration values are read in `Config.java`, which utilizes helper methods in `ConfigProvider.java` to fetch the final value for a configuration after searching through all Configuration Sources and determining the final value based on Source priority. |
There was a problem hiding this comment.
I think it's alright to document this now in dd-trace-java docs; in our conversations, I meant that public docs (docs.datadoghq.com) must wait.
The name for this file-based config stuff is definitely, officially Declarative Config 😁 .
Happy to help craft the sources doc if need be.
| } | ||
| } | ||
| ``` | ||
| 8. If the configuration is unique to all tracing libraries, add it to the [Feature Parity Dashboard](https://feature-parity.us1.prod.dog/#/configurations?viewType=configurations). This ensures that we have good documentation of all configurations supported in the library. |
There was a problem hiding this comment.
Suggested change
| 8. If the configuration is unique to all tracing libraries, add it to the [Feature Parity Dashboard](https://feature-parity.us1.prod.dog/#/configurations?viewType=configurations). This ensures that we have good documentation of all configurations supported in the library. | |
| 8. If the configuration is unique to this library, add it to the [Feature Parity Dashboard](https://feature-parity.us1.prod.dog/#/configurations?viewType=configurations). This ensures that we have good documentation of all configurations supported in the library. |
There was a problem hiding this comment.
This was intentional. If we are adding a config to Java that exists in other libraries, we expect it to already be documented in the FPD
|
|
||
| ## Verifying the Configuration | ||
|
|
||
| To verify a configuration has been correctly added, developers can modify existing test cases in `ConfigTest.groovy` to set the value of the configuration with various sources and confirm the internal value is correctly set in `Config.java`. |
There was a problem hiding this comment.
Would be sick to have a new test populate for the new config automatically... maybe someday. 😄
There was a problem hiding this comment.
Not sure that "automated generated tests" will have real value if it's only testing "getter" behavior to comply with the code coverage policy.
To me, it make sense to write tests when there is a specific logic at play, like this will be enabled if both X and Y are enable and Z contains xxx.
On thing I would like at mid term is to have:
- Config declaration per product -- like we have today TracerConfig, CiVisibilityConfig
- Such config would declare keys, aliases, type (and parser if needed)
- This config declaration would be used to generate the
Configclass(es).
It does not have to be a god class with all config from it, it can be split by products too.
But this would get rid of the contructor / getter / toString / testing boilerplate...
There was a problem hiding this comment.
Sounds like this could be something Config Inversion/Registry could be very useful for with our new v2 format. :)
manuel-alvarez-alvarez
approved these changes
Oct 27, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What Does This Do
There is currently no documentation in the tracer on how to add a new configuration in
dd-trace-java. With the addition of Config Inversion, docs are necessary to describe how to properly create new configurations in the tracer.Motivation
Additional Notes
Contributor Checklist
type:and (comp:orinst:) labels in addition to any useful labelsclose,fixor any linking keywords when referencing an issue.Use
solvesinstead, and assign the PR milestone to the issueJira ticket: [PROJ-IDENT]