awesome-copilot/plugins/phoenix/skills/phoenix-tracing/references/metadata-python.md

Phoenix Tracing: Custom Metadata (Python)

Add custom attributes to spans for richer observability.

Install

pip install arize-phoenix-otel  # context managers and SpanAttributes re-exported since 0.16.0

Session

from phoenix.otel import using_session

with using_session(session_id="my-session-id"):
    # Spans get: "session.id" = "my-session-id"
    ...

User

from phoenix.otel import using_user

with using_user("my-user-id"):
    # Spans get: "user.id" = "my-user-id"
    ...

Metadata

from phoenix.otel import using_metadata

with using_metadata({"key": "value", "experiment_id": "exp_123"}):
    # Spans get: "metadata" = '{"key": "value", "experiment_id": "exp_123"}'
    ...

Tags

from phoenix.otel import using_tags

with using_tags(["tag_1", "tag_2"]):
    # Spans get: "tag.tags" = '["tag_1", "tag_2"]'
    ...

Combined (using_attributes)

from phoenix.otel import using_attributes

with using_attributes(
    session_id="my-session-id",
    user_id="my-user-id",
    metadata={"environment": "production"},
    tags=["prod", "v2"],
    prompt_template="Answer: {question}",
    prompt_template_version="v1.0",
    prompt_template_variables={"question": "What is Phoenix?"},
):
    # All attributes applied to spans in this context
    ...

On a Single Span

span.set_attribute("metadata", json.dumps({"key": "value"}))
span.set_attribute("user.id", "user_123")
span.set_attribute("session.id", "session_456")

As Decorators

All context managers can be used as decorators:

from phoenix.otel import using_session, using_user, using_metadata

@using_session(session_id="my-session-id")
@using_user("my-user-id")
@using_metadata({"env": "prod"})
def my_function():
    ...