Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.odigos.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Considerations

Before enabling extract attribute, please note the following:
  • This action only operates on trace signals.
  • Extraction reads from a fixed set of high-cardinality string attributes and writes the captured value to a new span attribute. The source attributes are scanned in order until a match is found, and only the first match is used per extraction rule.
  • The action will scan the following span attributes for matches:
    • db.statement
    • db.query.text
    • messaging.message.payload
    • http.request.payload
    • http.response.payload
  • If the target attribute already exists on the span, it will not be overridden.
  • Each extraction must specify either source + dataFormat, or a custom regex — not both. When using regex, the pattern must contain exactly one capture group; the value of the first capture group is written to target.
  • Each target must be unique within a single action.

​
Use Cases

Accessing deeply nested attributes within strings
  • Easily extract and access values of deeply nested attributes within payloads of JSONs, SQL statements or URLs.
Indexing high-cardinality identifiers
  • Extract domain-specific identifiers (e.g. order_id, user_id, study_id) embedded inside payloads, SQL statements, or URL paths into top-level span attributes so they can be indexed, filtered, and aggregated by your backend.
Correlating spans across services
  • Lift correlation IDs that are buried inside structured payloads (JSON envelopes, request/response bodies) onto the span itself so traces can be searched and joined by business identifiers.
Cost-aware enrichment
  • Avoid sending the full payload to your backend by extracting only the meaningful fields, then dropping or masking the original payload attribute with another action.

​
Configuration Options

The ExtractAttribute action is configured using the odigos.io/v1alpha1.Action CRD with the extractAttribute configuration section.
actionName string : Allows you to attach a meaningful name to the action for convenience.
  • This field is optional
  • Odigos does not use or assume any meaning from this field
notes string : Allows you to attach notes regarding the action for convenience.
  • This field is optional
  • Odigos does not use or assume any meaning from this field
disabled boolean : Allows you to temporarily disable the action, but keep it saved for future use.
  • This field is optional, and defaults to false
signals string[] : An array with the signals that the action will operate on.
  • This field is required
  • Supported values: TRACES
extractAttribute object : Configuration for the ExtractAttribute action.
  • This field is required for this action type
extractions object[] : An ordered array of extraction rules to apply to each span. Must contain at least one entry.
  • This field is required
target string : The attribute key the extracted value will be written to on the span.
  • This field is required
  • Must be unique across all extractions in the same action.
source string : The key to look up inside the scanned attributes (resolved via dataFormat into a regex).
  • This field is required when dataFormat is set, and must be omitted when regex is set.
dataFormat string : A pre-set format that defines how source is matched inside the scanned attributes.
  • This field is required when source is set, and must be omitted when regex is set.
  • Supported values:
    • json — matches key: value / key = value pairs in JSON envelopes and in SQL statements (e.g. WHERE order_id = '42').
    • url — matches key/value segments inside URL paths (e.g. /projects/test-project), stopping at the next /, whitespace, ?, &, #, or quote.
regex string : A custom regular expression with a single capture group whose value is written to target.
  • This field is required when source and dataFormat are not set.
  • The first capture group of the first match is used.
Each extraction rule must use exactly one of:
  • source + dataFormat — for the built-in JSON/SQL/URL matchers, or
  • regex — for a custom pattern with a single capture group.

​
Basic Example

The following example demonstrates the four extraction variations against a single span that has the following attributes:
  • messaging.message.payload: {"task_id": "task-7f3a9b2c", "status": "Completed"}
  • http.request.payload: tenants/acme-corp/regions/us-east/workspaces/main/services/analytics/jobs/task-7f3a9b2c/runs/run-001
  • db.statement: SELECT * FROM invoices WHERE invoice_id = '42' -- request_id req-xyz9
After the action runs, the span will be enriched with the following extracted attributes:
Target attributeExtracted value
extracted.json.task_idtask-7f3a9b2c
extracted.sql.invoice_id42
extracted.url.tenantacme-corp
extracted.url.regionus-east
extracted.url.jobtask-7f3a9b2c
extracted.regex.request_idxyz9
1
Create a YAML file with the following content:
extract-attribute.yaml
apiVersion: odigos.io/v1alpha1
kind: Action
metadata:
  name: extract-attribute
  namespace: odigos-system
spec:
  actionName: extract attribute
  signals:
    - TRACES
  extractAttribute:
    extractions:
      # JSON variation - matches a JSON envelope inside messaging.message.payload
      - source: task_id
        dataFormat: json
        target: extracted.json.task_id

      # SQL variation - the json dataFormat also handles SQL `key = 'value'` syntax
      - source: invoice_id
        dataFormat: json
        target: extracted.sql.invoice_id

      # URL variation - matches `key/value` segments inside http.request.payload
      - source: tenants
        dataFormat: url
        target: extracted.url.tenant
      - source: regions
        dataFormat: url
        target: extracted.url.region
      - source: jobs
        dataFormat: url
        target: extracted.url.job

      # Custom regex variation - one capture group, value goes to target
      - regex: "req-([a-z0-9]+)"
        target: extracted.regex.request_id
2
Apply the action to the cluster:
kubectl apply -f extract-attribute.yaml