Guides

Practical guides for production instrumentation

Step-by-step playbooks for engineering and SRE — from first install to trusted signals in the control plane.

Overview

These guides assume you already have a PUVINoise tenant, an agent access key, and an OTLP endpoint URL from your platform team. They focus on what to do in order: install the SDK, emit a verified run, confirm tenant-scoped signals in operational views, then optionally adopt decision telemetry and schema v2 fields.

Authority pillars

Agent Observability & LLM Monitoring

Expanded pillar guides for buyers and operators evaluating Behaviour Runtime Intelligence.

Pillar

Agent Observability guide

Behaviour signals, tenancy, Command Centre, Runtime Cases — and how this differs from APM and LLM tracing.

Read Agent Observability →

Pillar

LLM Monitoring guide

From model/request metrics to behaviour runtime — where PUVINoise fits beside Langfuse, Helicone, and eval tools.

Read LLM Monitoring →

Reference guide: instrument → verify → hand off

Install and configure

Install with pip install puvinoise-sdk (optional extras: [anthropic], [openai], [all]). Set PUVINOISE_AGENT_NAME, PUVINOISE_TENANTID, PUVINOISE_API_KEY, PUVINOISE_END_POINT_URL, and CUST_LLM_PROVIDER. Call bootstrap() before agent work.

Emit a traced run

Wrap agent execution with run_with_trace so an agent.run span is created. Confirm resource attributes carry tenant.id and service.name. Optional: pass goal, task_type, and intent for behaviour intelligence.

Verify in Command Centre

Confirm traces appear under the correct tenant. Filter by agent name and LLM provider. Validate correlation and execution context before promoting instrumentation to wider fleets.

Upgrade and migrate safely

Upgrade with pip install --upgrade puvinoise-sdk. Schema v1 and v2 are both accepted; telemetry is never rejected based on SDK version. Adopt decision APIs and wrapAgent when ready — see the SDK migration notes.

Help Center

Tabbed troubleshooting for setup and runtime, plus concise FAQs for teams instrumenting agents with the PUVINoise SDK.

Troubleshooting

Setup

Install the SDK, choose provider extras, and call bootstrap() before any agent work.

pip install fails or wrong package
Install with pip install puvinoise-sdk. Use extras only when needed: [anthropic], [openai], or [all]. Confirm you are in the correct virtualenv for the agent runtime.
bootstrap() not called early enough
Call bootstrap() once at process start, before LLM clients or agent loops. Late bootstrap means early work never inherits OTLP resource attributes.
Provider extras missing
If you depend on Anthropic or OpenAI client helpers, install the matching extra. The core SDK still exports OTLP without extras; provider extras add optional integrations.

Frequently Asked Questions

Which package should I install?

Use pip install puvinoise-sdk. Optional extras include [anthropic], [openai], and [all] for provider-specific dependencies.

What environment variables are required?

PUVINOISE_AGENT_NAME, PUVINOISE_TENANTID, PUVINOISE_API_KEY, PUVINOISE_END_POINT_URL, and CUST_LLM_PROVIDER. Load them from the environment or a .env file before bootstrap().

Do I need to change my agent framework?

No. The SDK is an instrumentation layer. You keep ownership of agent logic, models, and hosting — wrap runs with run_with_trace and export OTLP to your collector.

Will an older SDK version be rejected?

No. Telemetry is never rejected based on SDK version or schema v1 vs v2. The backend may warn on older versions while still accepting events.

How do I emit intent and tool-selection signals?

Inside an active trace, use APIs such as record_intent_classification, record_tool_candidates, record_decision_confidence, and related helpers. You can also pass goal, task_type, and intent into run_with_trace.

How do I confirm first successful ingest?

After a traced run, open Command Centre for your tenant, filter by agent name and provider, and confirm tenant.id and service.name on the spans before rolling out fleet-wide.

Can I migrate gradually to schema v2?

Yes. Upgrade the package first, then optionally adopt decision APIs and wrapAgent. Both schema shapes are accepted during migration.

Where do I go for architecture and security review?

See Documentation for the telemetry contract, the SDK page for APIs, and Security for tenant isolation and audit posture suitable for reviewers.

Industry playbooks

Runtime outcomes by vertical

Deep playbooks for how the same control plane maps to industry-shaped risk. Each page includes FAQ structured for search and assistants. Dedicated solution hubs live under /solutions/{industry}.