feat: add process tags to traces

[wantsui]

What does this PR do?

The goal of AIDM-253 is to add process tags to the trace payloads.

After this gets merged, the next step is to add it for the other products.

To run the tests in docker

docker compose run --rm tracer-3.3 /bin/bash
bundle exec rake compile
bundle exec rake test:core_with_rails

Main tests:

BUNDLE_GEMFILE=/app/gemfiles/ruby_3.3_rails8.gemfile bundle exec rspec spec/datadog/core/environment/process_spec.rb
bundle exec rspec spec/datadog/tracing/transport/trace_formatter_spec.rb
bundle exec rspec spec/datadog/core/normalizer_spec.rb
bundle exec rspec spec/datadog/core/configuration/settings_spec.rb

Motivation:

We're trying to add process tags to various payloads so they can be used in different use cases.

Note I still want to try adding server type but I'll have to tackle that in a separate PR.

Change log entry

Yes. Add process tags to the trace payloads.

Additional Notes:

How to test the change?

[github-actions]

Thank you for updating Change log entry section 👏

^{Visited at: 2025-11-14 09:35:11 UTC}

[datadog-official]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage
• Patch Coverage: 100.61%
• Total Coverage: 98.50% (+0.05%)

View detailed report

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 23d9769 | Docs | Datadog PR Page | Was this helpful? Give us feedback!}

[marcotc]

This is impossible right? If so, we can remove it, as it would give us a false sense of uncertainty here.

[wantsui]

I think I fixed it in 8dae705 by just removing the check in process tags, but let me know if you spot issues with it!

[pr-commenter]

Benchmarks

Benchmark execution time: 2025-11-14 23:15:00

Comparing candidate commit 23d9769 in PR branch add-process-tags-to-tracing with baseline commit 49cee89 in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 44 metrics, 2 unstable metrics.

[wantsui]

@marcotc - do you think there's value in asserting for the values of the tag? Or is the test in process_spec enough?

[marcotc]

What you are doing with expect(first_span.meta['_dd.tags.process']).to eq(Datadog::Core::Environment::Process.serialized) seems good to me.

[marcotc]

I wouldn't test realistic values.

[marcotc]

The main thing to test here is that it's respecting the configuring option, which you did.

[marcotc]

The main thing to test here is that it's respecting the configuring option.

[wantsui]

Thanks! In that case it doesn't seem like I need to make any changes to the assertions then?

[github-actions]

Typing analysis

Note: Ignored files are excluded from the next sections.

Untyped methods

This PR introduces 1 partially typed method. It increases the percentage of typed methods from 54.67% to 54.8% (+0.13%).

Partially typed methods (+1-0)

❌ Introduced:

sig/datadog/core/normalizer.rbs:8
└── def self.normalize: (untyped original_value) -> ::String

If you believe a method or an attribute is rightfully untyped or partially typed, you can add # untyped:accept to the end of the line to remove it from the stats.

[marcotc]

Let's merge squeeze with the gsub above by changing the regex in the gsub to match one or more characters, instead of just one (regex +).
This saves us a string operation and string copy.

[wantsui]

Do you think this is still needed if there's a conditional check now to see if there are still double underscores: __?

        normalized_value.sub!(LEADING_INVALID_CHARS, "")
        normalized_value.sub!(TRAILING_UNDERSCORES, "")
        normalized_value.squeeze!('_') if normalized_value.include?('__')
        ```

[marcotc]

You can remove this comment, and the one for downcase, since they only capture what the code already does (and the code is not ambiguous).

[wantsui]

I ended up moving all the code comments up in a66e635, to clarify the order of operations based on the Trace Agent logic.

[tlhunter]

Suggested change

	# Merge consecutive underscores with a single underscore
	normalized_value.squeeze!('_')

Actually I don't believe we're supposed to do the squeeze (reduce multiple _ characters to a single character). Or at least the spec doesn't say to do so. Here the Python tracer leaves repeated underscores:

https://github.com/DataDog/dd-trace-py/pull/15146/files#diff-734f80f7c77b609471c1ca40c131a2604c2f50647ad9cf264863e2016f07b209R23

We should remove this to be consistent.

[wantsui]

I was following the Trace Agent, which has a test case seen here: https://github.com/DataDog/datadog-agent/blob/45799c842bbd216bcda208737f9f11cade6fdd95/pkg/trace/traceutil/normalize_test.go#L33

{in: "contiguous_____underscores", out: "contiguous_underscores"},

It looks like the Trace Agent merges them. I'll start a separate thread since I think we want this all to be consistent.

[Strech]

Is there a value of having range when it could be normalized_value[0, 200]?

[wantsui]

Not really, so I removed the range approach.

I played around with a few things here: 4747259 and now it looks like this:

normalized_value.slice!(MAX_CHARACTER_LENGTH..-1) if normalized_value.length > MAX_CHARACTER_LENGTH

(the conditional portion should help skip this operation if the text is small enough)

Let me know if this is more in line with what you're thinking of!

[Strech]

Minor: Could you please type it. You can use Codex, it's good at it

[wantsui]

Yes! Thanks for pointing this out! Addressed in adfa416!

[Strech]

untyped will cover everything, but still, it's not untyped, it's a ::String?

[wantsui]

Addressed in adfa416!

[marcotc]

We only need to specify namespacing in Ruby up until the common point between: the current class or module we are in; and the object we want to reference.
In this case, we are in Datadog::Core::Environment::Process and want to reference Datadog::Core::Environment::Ext::TAG_ENTRYPOINT_WORKDIR.

We can remove the prefix namespace that is identical. For example Ext::TAG_ENTRYPOINT_WORKDIR will work here.

BUT, Ruby namespace resolution is very lenient, and we will try to match Ext (from Ext::TAG_ENTRYPOINT_WORKDIR), in order, to: Datadog::Core::Environment::Process::Ext, Datadog::Core::Environment::Ext, Datadog::Core::Ext, Datadog::Ext, and ::Ext.
This is important because the namespace matching doesn't try to match the complete Ext::TAG_ENTRYPOINT_WORKDIR path; it only tries to match the first token you provided: the Ext in Ext::TAG_ENTRYPOINT_WORKDIR.
And because more than one of these locations in the possible search logic are realistic matches, we should be a bit more specific than Ext::TAG_ENTRYPOINT_WORKDIR.

A good practice is to stop at the closet common namespace location. In this case, it would be the Environment. So I suggest using Environment::Ext::TAG_ENTRYPOINT_WORKDIR (and the equivalent for the other constants) here.

[wantsui]

Thanks for the explanation! I'll keep this in mind going forward!
Addressed in: 31d9796

[marcotc]

We can remove Core:: from this constant access (see comment in def serialized).

[wantsui]

Thanks for this note! see 31d9796!

[marcotc]

Given how many operations happen inside this method, I recommend adding a "fast-case", where we do some checks and return immediately if the provided original_value is already valid.
This suggestion is equivalent to the early return by the agent here.

I suggest trying to use a regular expression, instead of implementing the agent's isNormalizedASCIITag in Ruby, since Ruby code is slower than Go code, but Ruby regex is pretty fast.

Something like:

return original_value if original_value.size <= MAX_CHARACTER_LENGTH && original_value.matches?(VALID_ASCII_TAG)

The hypothetical VALID_ASCII_TAG doesn't have to catch all valid cases: it's a trade-off between matching most valid tags vs making the regex complicated and slow. As long as it never matches invalid tags, it's all good.

[marcotc]

In general here: do we need NormalizeTag or NormalizeTagValue for process tags? https://github.com/DataDog/datadog-agent/blob/45799c842bbd216bcda208737f9f11cade6fdd95/pkg/trace/traceutil/normalize.go#L120-L129