Writer (tracing) | Respan Docs

Writer is an AI content platform with models for text, vision, translation, and knowledge graph workflows. Respan instruments Writer SDK calls and exports chat and text-generation spans for observability.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Setup

Install packages

$ pip install respan-ai respan-instrumentation-writer writerai

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export WRITER_API_KEY="YOUR_WRITER_API_KEY"

Optional:

$ export RESPAN_BASE_URL="https://api.respan.ai/api"
$ export WRITER_MODEL="palmyra-x5"

Initialize and run

1 import os
2 
3 from respan import Respan, workflow
4 from respan_instrumentation_writer import WriterInstrumentor
5 from writerai import Writer
6 
7 respan = Respan(
8     api_key=os.environ["RESPAN_API_KEY"],
9     base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
10     instrumentations=[WriterInstrumentor()],
11 )
12 
13 client = Writer(api_key=os.environ["WRITER_API_KEY"])
14 
15 
16 @workflow(name="writer_chat.workflow")
17 def run_writer_chat() -> str:
18     completion = client.chat.chat(
19         model=os.getenv("WRITER_MODEL", "palmyra-x5"),
20         messages=[{"role": "user", "content": "Write one line about tracing."}],
21         max_tokens=64,
22     )
23     return completion.choices[0].message.content
24 
25 
26 print(run_writer_chat())
27 respan.shutdown()

View your trace

Open the Traces page and search for workflow name writer_chat.workflow.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate, such as `WriterInstrumentor()` or `new WriterInstrumentor()`.
`sdkModule`	`object \| undefined`	`undefined`	TypeScript only. Pass the imported `writer-sdk` module for runtimes that resolve multiple module instances.
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag, such as `"production"`.

Supported calls

SDK call	Traced
`client.chat.chat(...)`	Chat completion spans, including streaming responses
`client.chat.parse(...)`	Structured-output chat spans
`client.chat.stream(...)`	Streaming chat spans after the stream is consumed
`client.completions.create(...)`	Text completion spans, including streaming completions

Attributes

In Respan()

1 from respan import Respan
2 from respan_instrumentation_writer import WriterInstrumentor
3 
4 respan = Respan(
5     instrumentations=[WriterInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "writer-api", "version": "1.0.0"},
8 )

With propagate_attributes

1 import os
2 
3 from respan import Respan, propagate_attributes
4 from respan_instrumentation_writer import WriterInstrumentor
5 from writerai import Writer
6 
7 respan = Respan(instrumentations=[WriterInstrumentor()])
8 client = Writer(api_key=os.environ.get("WRITER_API_KEY", "local-mock-token"))
9 
10 
11 def run_writer_with_attributes(user_id: str):
12     with propagate_attributes(
13         customer_identifier=user_id,
14         thread_identifier="writer_thread",
15         metadata={"plan": "enterprise"},
16     ):
17         completion = client.chat.chat(
18             model=os.getenv("WRITER_MODEL", "palmyra-x5"),
19             messages=[{"role": "user", "content": "Write one sentence for trace demos."}],
20             max_tokens=32,
21         )
22         print(completion.choices[0].message.content)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.