Built-in Observability

Overview

DeepIntShield includes built-in observability, a powerful feature that automatically captures and stores detailed information about every AI request and response that flows through your system. This provides structured, searchable data with real-time monitoring capabilities, making it easy to debug issues, analyze performance patterns, and understand your AI application’s behavior at scale.

All LLM interactions are captured with comprehensive metadata including inputs, outputs, tokens, costs, and latency. The logging plugin operates asynchronously with zero impact on request latency.

---

What’s Captured

DeepIntShield traces comprehensive information for every request, without any changes to your application code.

Request Data

• Input Messages: Complete conversation history and user prompts
• Model Parameters: Temperature, max tokens, tools, and all other parameters
• Provider Context: Which provider and model handled the request

Response Data

• Output Messages: AI responses, tool calls, and function results
• Performance Metrics: Latency and token usage
• Status Information: Success or error details

Custom Metadata

• Logging Headers: Capture configured request headers (e.g., X-Tenant-ID) into log metadata
• Ad-hoc Headers: Any x-bf-lh-* prefixed header is automatically captured into metadata
• See Logging Headers below for full details

Multimodal & Tool Support

• Audio Processing: Speech synthesis and transcription inputs/outputs
• Vision Analysis: Image URLs and vision model responses
• Tool Execution: Function calling arguments and results

---

Configuration

Configure request tracing to control what gets logged and where it’s stored from the Web UI.

1. Navigate to https://app.deepintshield.com
2. Go to “Settings”
3. Toggle “Enable Logs”

From the same settings you can also toggle:

• Enable Logs: Master toggle for request tracing.
• Disable Content Logging: Disable logging of request/response content, but still log usage metadata (latency, cost, token count, etc.).

---

Accessing & Filtering Logs

Retrieve and analyze logs with powerful filtering capabilities directly in the Web UI.

Web UI

Access the built-in dashboard at https://app.deepintshield.com. The UI provides:

• Real-time log streaming
• Advanced filtering and search
• Detailed request/response inspection
• Token and cost analytics

You can filter the log view by provider, model, request status, request type, time range, latency, token usage, cost, and free-text content search, and page through the results - ideal for analytics and debugging specific issues.

---

Log Store Options

Choose the right storage backend for your scale and requirements.

The logging plugin is automatically enabled with a log store by default. You can choose the log-store backend (SQLite or PostgreSQL) from the Web UI under Config → Logging.

Current Support

SQLite (Default)

• Best for: Development, small-medium deployments
• Performance: Excellent for read-heavy workloads
• Setup: Zero configuration, single file storage
• Limits: Single-writer, local filesystem only

PostgreSQL

• Best for: High-volume production deployments
• Performance: Excellent concurrent writes and complex queries
• Features: Advanced indexing, partitioning, replication
• Requirement: PostgreSQL database must be UTF8 encoded (see PostgreSQL UTF8 Requirement)
• Connection: Provide the host, port, database, and credentials in the Web UI.

Planned Support

• MySQL: For traditional MySQL environments.
• ClickHouse: For large-scale analytics and time-series workloads.

---

Supported Request Types

The logging plugin captures all DeepIntShield request types:

• Text Completion (streaming and non-streaming)
• Chat Completion (streaming and non-streaming)
• Responses (streaming and non-streaming)
• Embeddings
• Speech Generation (streaming and non-streaming)
• Transcription (streaming and non-streaming)
• Video Generation

---

Logging Headers

Capture specific HTTP request headers into the metadata field of every LLM and MCP log entry. This enables request tracing, tenant identification, and custom debugging without modifying your application code.

Two ways to capture headers

You can get request headers into log metadata in two ways:

1. Configured Logging Headers - Define a list of header names in the configuration. Each configured header (matched case-insensitively) is stored in the metadata of the matching log entry.

2. x-bf-lh-* Prefix (Automatic) - Send any request header with the x-bf-lh- prefix and it is captured into metadata with no configuration needed. The prefix is stripped and the remainder becomes the metadata key.

Request Header	Metadata Key	Metadata Value
x-bf-lh-tenant-id: acme	tenant-id	acme
x-bf-lh-env: production	env	production
x-bf-lh-region: us-east-1	region	us-east-1

Both methods can be used together - configured headers and x-bf-lh-* headers are merged into the same metadata map.

Configuring Logging Headers

1. Navigate to Config > Logging
2. Ensure Enable Logs is toggled on
3. Scroll to Logging Headers

4. Enter a comma-separated list of header names (e.g., X-Tenant-ID, X-Correlation-ID). Header matching is case-insensitive.
5. Click Save Changes

Changes take effect immediately - no restart required.

Usage Examples

Configured headers:

# Config has: logging_headers: ["X-Tenant-ID", "X-Correlation-ID"]
curl https://app.deepintshield.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "X-Tenant-ID: tenant-123" \
  -H "X-Correlation-ID: req-abc-456" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Log metadata: {"x-tenant-id": "tenant-123", "x-correlation-id": "req-abc-456"}

Ad-hoc x-bf-lh-* headers (no config needed):

curl https://app.deepintshield.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-bf-your-virtual-key" \
  -H "x-bf-lh-env: production" \
  -H "x-bf-lh-version: v2.1.0" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

Log metadata: {"env": "production", "version": "v2.1.0"}

Viewing Metadata in the UI

Metadata is displayed in the log detail view for both LLM and MCP logs as individual key-value entries alongside other request details.

Combining with Required Headers

Required headers and logging headers serve different purposes and can be used together:

Feature	Purpose	Effect on Request
Required Headers	Enforce header presence	Rejects request if missing (400)
Logging Headers	Capture header values	No effect on request - only logs metadata

A common pattern is to require a header and log it - add the same header (for example X-Tenant-ID) to both Required Headers and Logging Headers in the Web UI.

---

When to Use

Built-in Observability

Use the built-in logging plugin for:

• Local Development: Quick setup with SQLite, no external dependencies
• Self-hosted Deployments: Full control over your data with PostgreSQL
• Simple Use Cases: Basic monitoring and debugging needs
• Privacy-sensitive Workloads: Keep all logs on your infrastructure

vs. OTel Plugin

Switch to the OTel plugin for:

• Integration with existing observability infrastructure
• Correlation with application traces and metrics
• Custom collector configurations
• Compliance and enterprise requirements

---

Performance

Observability runs off the request path, so enabling it adds no measurable latency to your LLM calls (< 0.1ms in benchmarks). You can leave it on in production without worrying about request overhead.

---

Next Steps

• OTel Plugin - OpenTelemetry integration for distributed tracing
• Gateway Setup - Get DeepIntShield running with tracing enabled
• Provider Configuration - Configure multiple providers for better insights
• Telemetry - Prometheus metrics and dashboards
• Governance - Virtual keys and usage limits