​

Observability

• Connect your AI assistant to Langfuse for LLM observability
• Store your Langfuse credentials securely as integration secrets
• View traces, generations, and tool calls in the Langfuse dashboard
• Understand how conversations are grouped in traces

​

Overview

​

Key benefits

• Debugging: Inspect the exact messages sent to the LLM and the responses received.
• Cost tracking: Monitor token usage per conversation, assistant, or model.
• Quality evaluation: Review LLM outputs and tool call results to identify issues.
• Latency analysis: Measure response times for LLM calls and tool executions.
• Multi-tenant: Each assistant can connect to a different Langfuse project with its own credentials.

​

Requirements

1. A Langfuse account (cloud or self-hosted)
2. A Langfuse project with a public key and secret key
3. A Telnyx AI Assistant

​

Configuration

​

Step 1: Create your Langfuse credentials

​

Step 2: Store credentials as integration secrets

1. Langfuse Secret Key — store your Langfuse secret key as the secret value. Choose a memorable identifier (e.g., langfuse-secret-key).
2. Langfuse Public Key — store your Langfuse public key as the secret value. Choose a memorable identifier (e.g., langfuse-public-key).

​

Step 3: Enable observability on your assistant

curl --request POST \
  --url https://api.telnyx.com/v2/ai/assistants \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Observable Assistant",
    "model": "anthropic/claude-haiku-4-5",
    "instructions": "You are a helpful assistant.",
    "observability_settings": {
      "status": "enabled",
      "secret_key_ref": "langfuse-secret-key",
      "public_key_ref": "langfuse-public-key",
      "host": "https://cloud.langfuse.com"
    }
  }'

curl --request POST \
  --url https://api.telnyx.com/v2/ai/assistants/{assistant_id} \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "observability_settings": {
      "status": "enabled",
      "secret_key_ref": "langfuse-secret-key",
      "public_key_ref": "langfuse-public-key",
      "host": "https://cloud.langfuse.com"
    }
  }'

​

Disabling observability

curl --request POST \
  --url https://api.telnyx.com/v2/ai/assistants/{assistant_id} \
  --header "Authorization: Bearer $TELNYX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "observability_settings": {
      "status": "disabled"
    }
  }'

​

Observability settings reference

​

What you will see in Langfuse

​

Traces

• Name: The conversation name (if set), otherwise chat
• Metadata: conversation_id and assistant_id

​

Generations

• Model: The LLM model used (e.g., anthropic/claude-haiku-4-5)
• Input: The full message array sent to the model, including system prompt and conversation history
• Output: The model’s response content
• Token usage: Prompt tokens, completion tokens, and total tokens (non-streaming only)

​

Tool calls

• Name: tool-call-{tool_name}
• Input: The tool call arguments
• Output: The tool response

​

Best practices

​

Security

• Never share your Langfuse keys directly — always store them as Telnyx integration secrets.
• Use separate Langfuse projects for development and production assistants.
• Rotate keys periodically — update the integration secrets and the assistant configuration when you rotate Langfuse API keys.

​

Performance

• Observability adds minimal overhead. Traces are sent asynchronously and do not block conversation flow.
• If you are self-hosting Langfuse, ensure your instance is reachable from Telnyx infrastructure.

​

Organization

• Use conversation names to make traces easier to find in the Langfuse dashboard. Conversation names are set automatically and appear as the trace name.
• Filter by metadata in Langfuse to find traces for a specific conversation_id or assistant_id.

​

Troubleshooting

​

Traces not appearing in Langfuse

• Verify status is enabled: Check that observability_settings.status is "enabled" on your assistant.
• Verify credentials: Ensure your secret_key_ref and public_key_ref point to valid integration secrets with correct Langfuse keys.
• Check the host URL: Confirm the host field matches your Langfuse instance (e.g., https://cloud.langfuse.com for Langfuse Cloud).
• Check Langfuse project: Verify you are looking at the correct project in the Langfuse dashboard.

​

Missing output or token usage

• Token usage is captured for non-streaming LLM calls. Streaming calls may not include token counts depending on the model provider.
• Output is captured after the LLM response completes. If a call fails mid-stream, the output may be empty.

​

Secret reference errors

1. The integration secret exists in your Integration Secrets.
2. The identifier in secret_key_ref or public_key_ref exactly matches the secret name you created.
3. The secret belongs to the same organization as the assistant.

​

Observability not working after key rotation

1. Update the integration secret values in the portal.
2. The assistant will automatically use the new values on the next conversation — no assistant update is required.