feat: add injection metadata fields to telemetry forwarder (#13679)

## Overview
This change adds additional fields to the telemetry forwarder used
during injection. These fields will be used to add additional context
that will be surfaced to the end user in the following Figma:
<img width="1272" alt="Screenshot 2025-06-16 at 11 13 35 AM"
src="https://github.com/user-attachments/assets/c2070b96-fc55-4d38-bd4d-d43179c5a398"
/>

See [Injection
Metadata](https://docs.google.com/document/d/1wydXj2fW0V0jaWU6W9pIbipT_AXD15tmbTtOPXFBEy4/edit?tab=t.f3vpy615c2dp)
for more details.

## Testing Strategy 
I used this forwarder file to write output.json 
```bash 
#!/bin/bash


TELEMETRY_PAYLOAD=$(cat)

echo $TELEMETRY_PAYLOAD > /Users/sydney.tung/go/src/github.com/DataDog/sydney/output.json
```

I used this python app 
```python
#!/usr/bin/env python3

print("app complete")
```

I used this script 
```bash
#!/bin/bash
[ -f /Users/sydney.tung/go/src/github.com/DataDog/sydney/output.json ] && rm /Users/sydney.tung/go/src/github.com/DataDog/sydney/output.json

export DD_APM_INSTRUMENTATION_DEBUG="true"        #injector debug logging 
export DD_INJECTION_ENABLED=true                                         #injecting enable & forwarding 
export DD_TRACE_DEBUG=true                                              #debug logging for dd-trace-py
export PYTHONPATH=/Users/sydney.tung/go/src/github.com/DataDog/dd-trace-py/lib-injection/sources:$PYTHONPATH   #path -> sitecustomize.py
export DD_TELEMETRY_FORWARDER_PATH=/Users/sydney.tung/go/src/github.com/DataDog/sydney/forwarder.sh                       #which forwarder excuted 
python3 /Users/sydney.tung/go/src/github.com/DataDog/sydney/app.py                                            #random app 

cat /Users/sydney.tung/go/src/github.com/DataDog/sydney/output.json | jq
```
This is a sample output
```json
{
  "metadata": {
    "language_name": "python",
    "language_version": "3.13.3",
    "runtime_name": "cpython",
    "runtime_version": "3.13.3",
    "tracer_version": "unknown",
    "pid": 49533,
    "result": "unknown",
    "result_reason": "unknown",
    "result_class": "unknown"
  },
  "points": [
    {
      "name": "library_entrypoint.error",
      "tags": [
        "error_type:main_filenotfounderror"
      ]
    }
  ]
}
```
## Checklist
- [x] PR author has checked that all the criteria below are met
- The PR description includes an overview of the change
- The PR description articulates the motivation for the change
- The change includes tests OR the PR description describes a testing
strategy
- The PR description notes risks associated with the change, if any
- Newly-added code is easy to change
- The change follows the [library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
- The change includes or references documentation updates if necessary
- Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist
- [x] Reviewer has checked that all the criteria below are met 
- Title is accurate
- All changes are related to the pull request's stated goal
- Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes
- Testing strategy adequately addresses listed risks
- Newly-added code is easy to change
- Release note makes sense to a user of the library
- If necessary, author has acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment
- Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)

---------

Co-authored-by: brettlangdon <[email protected]>

Author: sydney-tung

lib-injection/sources/sitecustomize.py

@@ -56,6 +56,9 @@ def parse_version(version):
 PYTHON_VERSION = "unknown"
 PYTHON_RUNTIME = "unknown"
 DDTRACE_REQUIREMENTS = {}
+RESULT = "unknown"
+RESULT_REASON = "unknown"
+RESULT_CLASS = "unknown"
 EXECUTABLES_DENY_LIST = set()
 REQUIREMENTS_FILE_LOCATIONS = (
     os.path.abspath(os.path.join(SCRIPT_DIR, "../datadog-lib/requirements.csv")),
@@ -162,6 +165,9 @@ def gen_telemetry_payload(telemetry_events, ddtrace_version):
             "runtime_version": PYTHON_VERSION,
             "tracer_version": ddtrace_version,
             "pid": os.getpid(),
+            "result": RESULT,
+            "result_reason": RESULT_REASON,
+            "result_class": RESULT_CLASS,
         },
         "points": telemetry_events,
     }
@@ -275,6 +281,9 @@ def _inject():
     global DDTRACE_REQUIREMENTS
     global EXECUTABLES_DENY_LIST
     global TELEMETRY_DATA
+    global RESULT
+    global RESULT_REASON
+    global RESULT_CLASS
     # Try to get the version of the Python runtime first so we have it for telemetry
     PYTHON_VERSION = platform.python_version()
     PYTHON_RUNTIME = platform.python_implementation().lower()
@@ -321,6 +330,9 @@ def _inject():
                         "library_entrypoint.abort.integration",
                     )
                 )
+                RESULT = "abort"
+                RESULT_REASON = "Found incompatible executable: %s." % incompatible_sysarg
+                RESULT_CLASS = "incompatible_runtime"
             else:
                 _log(
                     "DD_INJECT_FORCE set to True, allowing unsupported executables and continuing.",
@@ -351,6 +363,9 @@ def _inject():
                         )
                     )
 
+                RESULT = "abort"
+                RESULT_REASON = "Found incompatible packages: %s." % incompatible_packages
+                RESULT_CLASS = "incompatible_runtime"
             else:
                 _log(
                     "DD_INJECT_FORCE set to True, allowing unsupported dependencies and continuing.",
@@ -368,6 +383,13 @@ def _inject():
                 abort = True
 
                 TELEMETRY_DATA.append(create_count_metric("library_entrypoint.abort.runtime"))
+                RESULT = "abort"
+                RESULT_REASON = "Found incompatible runtime: %s %s. Supported runtimes: %s" % (
+                    PYTHON_RUNTIME,
+                    PYTHON_VERSION,
+                    RUNTIMES_ALLOW_LIST,
+                )
+                RESULT_CLASS = "incompatible_runtime"
             else:
                 _log(
                     "DD_INJECT_FORCE set to True, allowing unsupported runtimes and continuing.",
@@ -393,6 +415,9 @@ def _inject():
             TELEMETRY_DATA.append(
                 create_count_metric("library_entrypoint.abort", ["reason:missing_" + site_pkgs_path]),
             )
+            RESULT = "error"
+            RESULT_REASON = "ddtrace site-packages not found in %r, aborting" % site_pkgs_path
+            RESULT_CLASS = "incorrect_installation"
             return
 
         # Add the custom site-packages directory to the Python path to load the ddtrace package.
@@ -411,7 +436,9 @@ def _inject():
                     "library_entrypoint.error", ["error_type:import_ddtrace_" + type(e).__name__.lower()]
                 ),
             )
-
+            RESULT = "error"
+            RESULT_REASON = "Failed to load ddtrace module: %s" % e
+            RESULT_CLASS = "internal_error"
             return
         else:
             try:
@@ -457,12 +484,18 @@ def _inject():
                         ],
                     ),
                 )
+                RESULT = "success"
+                RESULT_REASON = "Successfully configured ddtrace package"
+                RESULT_CLASS = "success" if not (runtime_incomp or integration_incomp) else "success_forced"
             except Exception as e:
                 TELEMETRY_DATA.append(
                     create_count_metric(
                         "library_entrypoint.error", ["error_type:init_ddtrace_" + type(e).__name__.lower()]
                     ),
                 )
+                RESULT = "error"
+                RESULT_REASON = "Failed to load ddtrace.bootstrap.sitecustomize: %s" % e
+                RESULT_CLASS = "internal_error"
                 _log("failed to load ddtrace.bootstrap.sitecustomize: %s" % e, level="error")
                 return
     else:
@@ -476,6 +509,9 @@ def _inject():
                 ],
             )
         )
+        RESULT = "abort"
+        RESULT_REASON = "User-installed ddtrace found: %s, aborting site-packages injection" % module_origin
+        RESULT_CLASS = "already_instrumented"
 
 
 try:

releasenotes/notes/add-injection-metadata-fields-5f2d35cc9636c864.yaml

@@ -0,0 +1,4 @@
+---
+other:
+  - | 
+    lib-injection: Additional fields have been added to the telemetry forwarder used during Single Step to surface troubleshooting insights in the Datadog UI.