Pi Telemetry Docs

Target: Pi extension for runtime telemetry with Langfuse and OpenTelemetry exporters.

🚀 Quick Start

• Install: pi install npm:@amaster.ai/pi-telemetry
• Internal Alias: Source code exposes package as @lifanh/pi-langfuse-extension using Langfuse/OpenTelemetry Node SDKs.

🔧 Configuration

• Resolution Order: Environment variables > project .pi/settings.json > ~/.pi/agent/@lifanh/pi-langfuse-extension/config.json.
• Core Env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST (Defaults to https://cloud.langfuse.com).
• Capture Flags (Opt-in): LANGFUSE_CAPTURE_INPUTS, LANGFUSE_CAPTURE_OUTPUTS, LANGFUSE_CAPTURE_TOOL_IO, LANGFUSE_CAPTURE_SYSTEM_PROMPT, LANGFUSE_CAPTURE_CWD.

💡 Best Practices & Patterns

• Opt-In Privacy & Redaction: All sensitive string payloads (prompts, outputs, tool I/O) aggressively default to [REDACTED]. Explicit configuration is required to log actual content, preventing accidental PII leaks.
• Fail-Safe Transport: Telemetry operations strictly swallow errors via a global logError() tracker. Agent executions are completely isolated from network timeouts or missing API keys.
• Cross-Provider Content Normalization: Automatically restructures disparate provider tool call objects (Anthropic’s tool_use array vs. OpenAI’s tool_calls). This ensures standard trace UI compatibility inside Langfuse.
• Hierarchical Attribute Inheritance: Agent trace metadata, session.id, and trace names are mapped via a WeakMap. All subsequent generation and tool child spans automatically inherit attributes losslessly.
• Idempotent Connection Init: Langfuse span processor instantiation is gated by a hash of the current config credentials. Identical config re-initializations bypass redundant connection setup.

🚨 Gotchas / Warnings (Anti-Patterns)

• Opaque Default Traces: Overlooking the LANGFUSE_CAPTURE_* boolean flags results in trace UI dashboards populated entirely by [REDACTED] strings.
• Metadata Truncation Limits: Any propagated string tag or metadata value exceeding exactly 200 characters (MAX_PROPAGATED_STRING_LENGTH) is silently dropped.
• Array Payload Coercion: Custom metadata objects containing numbers or booleans are forcibly coerced to strings via coerceMetadataToStrings(). Deeply nested objects or null values are skipped and lost.
• Volatile Buffer Exit: Spans are heavily memory-buffered by default. A forceful SIGKILL or unhandled promise rejection without awaiting the shutdown() hook drops pending OTLP/HTTP traces.
• Orphaned Session Identifiers: sessionId heavily depends on resolving sessionManager.getSessionFile(). Using ephemeral, memory-only session managers without mock filenames breaks trace continuity.

📦 Dependencies

• @langfuse/otel, @langfuse/tracing
• @opentelemetry/api, @opentelemetry/core, @opentelemetry/exporter-trace-otlp-http

🔍 Research / References

• NPM Package: @amaster.ai/pi-telemetry
• Source Extracted: amaster.ai-pi-telemetry-0.1.3.tgz