Attach Business Context to Dynatrace PurePaths with Request Attributes

The Problem: PurePaths Lack Business Context

Dynatrace captures every hop of a distributed trace, but the raw PurePath only shows technical metadata — service names, HTTP status, response time. To answer questions like "show me all requests for tenant Acme" or "which feature flag caused the latency spike?" you need business values attached to each request. Request attributes are Dynatrace's supported mechanism for doing exactly that without changing application code.

How Request Attributes Work

You define a named attribute in Settings → Server-side service monitoring → Request attributes. Each attribute has one or more data sources that tell OneAgent where to pull the value at capture time. Supported source types include:

• HTTP headers
• Query parameters
• Cookies
• Session attributes (Java servlet / ASP.NET Core)
• Method invocations on Java or .NET — specify class, method, and which argument (or a getter chain on the return value) to capture

When a server-side request arrives, OneAgent evaluates the sources in order and stores the first non-empty value on that request's PurePath node. You can then filter Transactions & PurePaths, distributed traces, or the request-attribute analysis view by that attribute.

Worked Example: Capture Tenant ID from a Gateway Header

Assume your API gateway injects X-Tenant-Id on every inbound request. You want that value searchable in Dynatrace.

1. Open Settings → Server-side service monitoring → Request attributes.
2. Click Add request attribute.
3. Name: tenantId (no spaces, used in filters and DQL).
4. Data source: HTTP header → Header name: X-Tenant-Id.
5. Optional: toggle Personal data if the tenant ID is considered PII under your policy. This enables Dynatrace's masking and retention handling.
6. Save.

OneAgent picks up the rule within a minute or two (no process restart required for header sources). Send a test request:

curl -H "X-Tenant-Id: acme" https://api.example.com/orders

Open Transactions & PurePaths, filter by tenantId = acme, and the PurePath appears with the attribute value visible on the entry-point node.

Method-Capture Variant: Values That Only Exist Inside Code

Sometimes the business value isn't on the wire — it's computed inside a service method. Example: a Java method OrderService.calculateTotal(String tenantId, double amount) where tenantId is derived from a thread-local context.

1. In the same Request attributes screen, add a second data source to tenantId (or create a new attribute).
2. Source type: Method invocation.
3. Class: com.example.orders.OrderService.
4. Method: calculateTotal.
5. Capture: Argument 1 (zero-based index; argument 0 is this).
6. Type: String.
7. Save.

Critical constraint: the method must execute inside an already-captured request. Background threads, scheduled jobs, or entry points not instrumented by OneAgent will not produce a value. Method rules also require the target process to re-instrument — typically a process restart — before values appear.

Engineering Decision: Prefer Headers Over Deep Method Capture

Approach	Pros	Cons
HTTP header / gateway injection	Language-agnostic, survives refactors, zero code coupling, immediate pickup	Requires gateway or middleware cooperation
Method invocation	Captures values that never leave the process	Couples monitoring to private method signatures; breaks on refactor; needs process restart; only fires inside captured requests

Reserve method capture for values that genuinely exist only inside the code path (e.g., a feature flag evaluated by a legacy library with no header exposure).

What You Get — and What You Don't

• Per-request data: each PurePath node carries the attribute value. Filter traces, build top-value charts in the request-attribute analysis view.
• Not automatic metrics: you cannot alert on tenantId = acme latency directly. To alert, create a calculated service metric from the attribute (Settings → Calculated service metrics) or use DQL in Notebooks/Dashboards — extra steps, not free.
• Server-side only: browser-side context (user ID, A/B variant) uses user tags or session properties, not request attributes.

Limits and Common Mistakes

• Truncation: captured values are truncated at a platform-dependent length (typically 250–1000 characters). Do not stuff JSON blobs or long URLs.
• PII handling: always mark attributes containing personal data (email, user ID) as Personal data. Unmarked PII violates GDPR and Dynatrace's data-processing terms.
• Attribute count: per-environment limits exist and change with releases. Check current documentation before creating dozens of attributes.
• Method capture outside PurePaths: a call to OrderService.calculateTotal from a Quartz job will not record anything because no request context exists.
• Stale rules: after changing a method-capture rule, restart the target process group (or wait for OneAgent's hot-swap, which is not guaranteed for all runtimes).

Verify in Your Tenant

1. In a trial or non-prod tenant, create the tenantId header attribute as above.
2. Send a request with the header from a test client.
3. Within 2–3 minutes, open a recent PurePath and confirm tenantId appears under Request attributes on the entry node.
4. For method capture, deploy the rule, restart the instrumented service, invoke the endpoint that calls the method, then inspect the PurePath node where the method executes.

If the value doesn't appear, check Process group → Properties → OneAgent configuration that the rule is listed, and verify the method signature matches exactly (including generics erasure for Java).

Summary

Request attributes are the supported, low-friction way to make PurePaths queryable by business context. Define them in Settings, prefer header sources, mark PII explicitly, and remember they are per-request filters — not metrics — until you build a calculated metric on top.