Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tryheimdall.com/llms.txt

Use this file to discover all available pages before exploring further.

Heimdall SDKs can be fully configured using environment variables. This is the recommended approach for production deployments.

​
Available Variables

VariableDescriptionDefault
HEIMDALL_ENDPOINTBackend OTLP endpoint URLhttp://localhost:4318
HEIMDALL_ORG_IDOrganization ID from dashboarddefault
HEIMDALL_PROJECT_IDProject ID for trace groupingdefault
HEIMDALL_SERVICE_NAMEService name in tracesmcp-server
HEIMDALL_ENVIRONMENTEnvironment tag (e.g., production, staging)development
HEIMDALL_ENABLEDEnable/disable tracingtrue
HEIMDALL_API_KEYAPI key for authentication (optional)-
HEIMDALL_DEBUGEnable debug loggingfalse
HEIMDALL_BATCH_SIZENumber of spans to batch before sending100
HEIMDALL_FLUSH_INTERVAL_MSFlush interval in milliseconds5000

​
Configuration Examples

​
Basic Setup

Set the required environment variables: 
export HEIMDALL_ENDPOINT="http://localhost:4318"
export HEIMDALL_ORG_ID="my-organization"
export HEIMDALL_PROJECT_ID="my-project"
export HEIMDALL_ENABLED="true"
Then initialize the client without arguments: 
from hmdl import HeimdallClient

client = HeimdallClient()

​
Production Setup

For production environments, include service name and environment: 
export HEIMDALL_ENDPOINT="https://heimdall.yourcompany.com:4318"
export HEIMDALL_ORG_ID="production-org"
export HEIMDALL_PROJECT_ID="api-service"
export HEIMDALL_SERVICE_NAME="api-service"
export HEIMDALL_ENVIRONMENT="production"
export HEIMDALL_ENABLED="true"

​
Development Setup

For local development with debug logging: 
export HEIMDALL_ENDPOINT="http://localhost:4318"
export HEIMDALL_ORG_ID="dev-org"
export HEIMDALL_PROJECT_ID="dev-project"
export HEIMDALL_SERVICE_NAME="my-mcp-server"
export HEIMDALL_ENVIRONMENT="development"
export HEIMDALL_DEBUG="true"
export HEIMDALL_ENABLED="true"

​
Disable Tracing

To completely disable tracing (useful for tests): 
export HEIMDALL_ENABLED="false"
When disabled, all tracing decorators become no-ops and no data is sent.

​
Using .env Files

​
Python with python-dotenv

# .env file
HEIMDALL_ENDPOINT=http://localhost:4318
HEIMDALL_ORG_ID=my-org
HEIMDALL_PROJECT_ID=my-project
HEIMDALL_SERVICE_NAME=my-mcp-server
HEIMDALL_ENVIRONMENT=development
HEIMDALL_ENABLED=true

from dotenv import load_dotenv
from hmdl import HeimdallClient

load_dotenv()  # Load .env file

client = HeimdallClient()

​
Node.js with dotenv

# .env file
HEIMDALL_ENDPOINT=http://localhost:4318
HEIMDALL_ORG_ID=my-org
HEIMDALL_PROJECT_ID=my-project
HEIMDALL_SERVICE_NAME=my-mcp-server
HEIMDALL_ENVIRONMENT=development
HEIMDALL_ENABLED=true

import 'dotenv/config';
import { HeimdallClient } from 'hmdl';

const client = new HeimdallClient();

​
Priority Order

Configuration values are resolved in the following order (highest priority first):
  1. Explicit arguments passed to HeimdallClient()
  2. Environment variables
  3. Default values
This means you can override specific settings while using environment variables for the rest: 
# Uses HEIMDALL_ENDPOINT from environment, but overrides service_name
client = HeimdallClient(service_name="custom-service")

​
Docker Configuration

When running in Docker, pass environment variables using -e flags or an env file: 
docker run -e HEIMDALL_ENDPOINT=http://host.docker.internal:4318 \
           -e HEIMDALL_ORG_ID=my-org \
           -e HEIMDALL_PROJECT_ID=my-project \
           my-mcp-server
Or with docker-compose: 
version: '3'
services:
  mcp-server:
    image: my-mcp-server
    environment:
      - HEIMDALL_ENDPOINT=http://heimdall-backend:4318
      - HEIMDALL_ORG_ID=my-org
      - HEIMDALL_PROJECT_ID=my-project
      - HEIMDALL_SERVICE_NAME=mcp-server
      - HEIMDALL_ENVIRONMENT=production

​
Kubernetes Configuration

Use ConfigMaps and Secrets for Kubernetes deployments: 
apiVersion: v1
kind: ConfigMap
metadata:
  name: heimdall-config
data:
  HEIMDALL_ENDPOINT: "http://heimdall-backend.monitoring:4318"
  HEIMDALL_ENVIRONMENT: "production"
  HEIMDALL_ENABLED: "true"
---
apiVersion: v1
kind: Secret
metadata:
  name: heimdall-secrets
type: Opaque
stringData:
  HEIMDALL_ORG_ID: "my-org"
  HEIMDALL_PROJECT_ID: "my-project"
  HEIMDALL_API_KEY: "secret-api-key"

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: mcp-server
        envFrom:
        - configMapRef:
            name: heimdall-config
        - secretRef:
            name: heimdall-secrets

​
Next Steps

SDK Options

Explore programmatic configuration options.

Quickstart

Get started with Heimdall.