First run

Start the local receiver, ELT worker, and dashboard:

npx -y witdem@0.2.0 up

That pulls the version-matched container, starts all three services, waits for them to become healthy, and opens http://localhost:8501. Docker with Compose is the only prerequisite. Data persists across down and package upgrades.

npx -y witdem@0.2.0 status
npx -y witdem@0.2.0 logs
npx -y witdem@0.2.0 down

Add the SDK to an existing Haystack 3 project from the checkout:

python -m pip install -e "/path/to/Witdem-Analytics/witdem-sdk[haystack]"
export WITDEM_ENDPOINT=http://localhost:4318

Wrap the pipeline once. Its existing run, run_async, and run_async_generator calls stay unchanged:

from witdem_sdk.integrations.haystack import instrument

pipeline = instrument(build_pipeline())
result = pipeline.run(data)

Add .witdem/witdem.yaml to describe what a useful result means:

version: 1
service:
  name: support-agent
  runtime: haystack
telemetry:
  capture_content: false
contracts:
  - name: answer
    mode: expression
    artifact:
      name: Support answer
      valid:
        non_empty: $.answer
    decision:
      name: Result validity
      expected: true
      observed: $.witdem.artifact_valid
    product_goal:
      name: Useful answer returned
      achieved: $.witdem.artifact_valid

Run the application normally. The execution and its business result appear at http://localhost:8501.

witdem-sdk 0.2.0 is not yet published to the package index. The source-checkout command above is the verified installation path for this release. Publishing the package is the remaining installation launch blocker.

What you get

• Actual execution paths, branches, loops, retries, tools, model calls, and failures
• Per-run latency, token usage, and cost when provider/model/usage evidence is sufficient
• Application outcomes and product-goal success defined by your application
• Provider and model comparisons using attributable time, usage, cost, and quality
• Workflow/path analytics and run-linked issue investigation
• Local DuckDB storage and a self-hosted dashboard; prompt and response capture is off by default

Witdem does not infer business success from a completed LLM call. Framework instrumentation records what happened technically; .witdem/witdem.yaml explains what the final result means.

Integration status

Statuses reflect current implementation and test evidence, not roadmap intent.

See compatibility.json for machine-readable version constraints and Providers for the difference between native, framework-observed, and generic support.

Providers

Witdem currently has verified paths for:

• OpenAI and Azure OpenAI
• Anthropic, including Claude Agent SDK telemetry
• DeepSeek
• Mistral
• Amazon Bedrock
• Google Vertex AI
• Ollama
• Cohere (structurally tested, not live-validated)
• OpenRouter, including selected upstream provider and fallback metadata
• Hugging Face inference through smolagents or LiteLLM

OpenAI and Anthropic have dedicated SDK integrations. Haystack observes the generator actually used at each model boundary. The remaining provider examples use standard GenAI OpenTelemetry attributes or witdem_sdk.integrations.generic; this is explicit in every provider guide.

Cost is not assumed from a provider name. Witdem uses provider-reported money when present, or the versioned server catalog when provider, model, and token usage match a catalog entry. Unknown prices remain Not measured with a diagnostic reason.

Parallel and asynchronous execution

When sibling spans overlap, Witdem preserves the observed fan-out and fan-in rather than flattening them into a false sequence:

             ┌─ semantic retriever ─┐
execution ───┤                      ├─ answer
             └─ keyword retriever ──┘

The runnable Haystack parallel pipeline demonstrates this with two concurrent retrievers and an OpenAI answer component.

Self-hosting

The npm launcher is the recommended local backend path. It is deliberately a small, dependency-free Docker launcher rather than a second implementation of Witdem. It never runs an npm postinstall script.

npx -y witdem@0.2.0 status
curl http://localhost:4318/readiness
curl http://localhost:8501/health

For source development, clone the repository and run docker compose up -d. See Running Witdem with npx for ports, lifecycle, image pinning, and troubleshooting.

The Python-only development path is also available:

uv sync
uv run witdem dev --open

Documentation

• Getting started
• Running Witdem with npx
• Concepts: tracing and business meaning
• Tutorial: defining a YAML contract
• YAML configuration
• Haystack
• LangGraph
• LangChain
• Native/custom Python
• OpenAI Agents
• Anthropic and Claude Agent
• Provider support
• Pricing catalog and automated refresh
• Dashboard
• Troubleshooting
• Examples
• Operations
• Development and contributing

Built with

Local analytics storage

Raw-to-serving transformation

Dashboard routing, queries, and tables

Witdem is independent of these projects. Their names and unmodified marks identify the technologies used and do not imply endorsement.