apunkt/plano
1
0
Fork 0
mirror of https://github.com/katanemo/plano.git synced 2026-07-23 16:51:04 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: custom span attributes section to include static attributes and clarify configuration

Browse source
This commit is contained in:
Musa 2026-02-06 11:53:45 -08:00
parent 20e9953a8e
commit dd63599fd0
No known key found for this signature in database
1 changed files with 30 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/source/guides/observability/tracing.rst
View file

@ -145,7 +145,8 @@ For complete details on all available signals, detection methods, and best pract
Custom Span Attributes Custom Span Attributes
------------------------------------------- -------------------------------------------
Plano can automatically attach **custom span attributes** derived from request headers. This lets you stamp Plano can automatically attach **custom span attributes** derived from request headers and **static** attributes
defined in configuration. This lets you stamp
traces with identifiers like workspace, tenant, or user IDs without changing application code or adding traces with identifiers like workspace, tenant, or user IDs without changing application code or adding
custom instrumentation. custom instrumentation.
@ -159,18 +160,24 @@ How It Works
~~~~~~~~~~~~ ~~~~~~~~~~~~
You configure one or more header prefixes. Any incoming HTTP header whose name starts with one of these You configure one or more header prefixes. Any incoming HTTP header whose name starts with one of these
prefixes is captured as a span attribute. prefixes is captured as a span attribute. You can also provide static attributes that are always injected.
- The **prefix is only for matching**, not the resulting attribute key. - The **prefix is only for matching**, not the resulting attribute key.
- The attribute key is the header name **with the prefix removed**, then hyphens converted to dots. - The attribute key is the header name **with the prefix removed**, then hyphens converted to dots.
.. note::
Custom span attributes are attached to LLM spans when handling ``/v1/...`` requests via ``llm_chat``. For orchestrator requests to ``/agents/...``,
these attributes are added to both the orchestrator selection span and to each agent span created by ``agent_chat``.
**Example** **Example**
Configured prefix:: Configured prefix::
tracing: tracing:
span_attribute_header_prefixes: span_attributes:
- x-katanemo- header_prefixes:
- x-katanemo-
Incoming headers:: Incoming headers::
@ -191,17 +198,28 @@ Add the prefix list under ``tracing`` in your config:
tracing: tracing:
random_sampling: 100 random_sampling: 100
span_attribute_header_prefixes: span_attributes:
- x-katanemo- header_prefixes:
- x-katanemo-
static:
environment: production
service.version: "1.0.0"
Static attributes are always injected alongside any header-derived attributes. If a header-derived
attribute key matches a static key, the header value overrides the static value.
You can provide multiple prefixes: You can provide multiple prefixes:
.. code-block:: yaml .. code-block:: yaml
tracing: tracing:
span_attribute_header_prefixes: span_attributes:
- x-katanemo- header_prefixes:
- x-tenant- - x-katanemo-
- x-tenant-
static:
environment: production
service.version: "1.0.0"
Notes and Examples Notes and Examples
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
@ -216,8 +234,9 @@ Notes and Examples
Config:: Config::
tracing: tracing:
span_attribute_header_prefixes: span_attributes:
- x-katanemo- header_prefixes:
- x-katanemo-
Request headers:: Request headers::