Skip to main content
This page provides a complete reference for all configuration options available in the Heimdall SDKs.

​
Client Configuration

​
HeimdallClient Options

These options are passed when initializing the HeimdallClient:
OptionPythonJavaScriptTypeDefaultDescription
Endpointendpointendpointstringhttp://localhost:4318Heimdall backend URL
Organization IDorg_idorgIdstringdefaultYour organization ID
Project IDproject_idprojectIdstringdefaultYour project ID
Service Nameservice_nameserviceNamestringmcp-serverName of your service
EnvironmentenvironmentenvironmentstringdevelopmentDeployment environment
API Keyapi_keyapiKeystring-Optional API key
DebugdebugdebugbooleanfalseEnable debug logging
EnabledenabledenabledbooleantrueEnable/disable tracing
Batch Sizebatch_sizebatchSizenumber100Spans to batch
Flush Intervalflush_interval_msflushIntervalMsnumber5000Flush interval (ms)

​
Python Example

from hmdl import HeimdallClient

client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="my-organization",
    project_id="my-project",
    service_name="document-server",
    environment="production",
    api_key="optional-api-key",
    debug=False,
    enabled=True,
    batch_size=100,
    flush_interval_ms=5000
)

​
JavaScript Example

import { HeimdallClient } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "my-organization",
  projectId: "my-project",
  serviceName: "document-server",
  environment: "production",
  apiKey: "optional-api-key",
  debug: false,
  enabled: true,
  batchSize: 100,
  flushIntervalMs: 5000
});

​
Tracing Decorator Options

​
trace_mcp_tool / traceMCPTool

Options for the MCP tool tracing decorator:
OptionPythonJavaScriptTypeDefaultDescription
Namename (positional)namestringfunction nameCustom span name
Parameter NamesN/AparamNamesstring[]-Names for positional args
Capture InputN/AcaptureInputbooleantrueWhether to capture inputs
Capture OutputN/AcaptureOutputbooleantrueWhether to capture outputs
Python SDK automatically captures parameter names using introspection, so paramNames is not needed.

​
Python Examples

from hmdl import trace_mcp_tool

# Basic usage - uses function name as span name
@trace_mcp_tool()
def search(query: str) -> dict:
    return {"results": []}

# Custom span name
@trace_mcp_tool("document-search")
def search(query: str) -> dict:
    return {"results": []}

​
JavaScript Examples

import { traceMCPTool } from 'hmdl';

// Basic usage
const search = traceMCPTool(
  async (query: string) => ({ results: [] }),
  { name: "search" }
);

// With parameter names for better display
const searchWithParams = traceMCPTool(
  async (query: string, limit: number) => ({ results: [] }),
  { 
    name: "search",
    paramNames: ["query", "limit"]
  }
);

// Disable input/output capture for sensitive data
const sensitiveOperation = traceMCPTool(
  async (secretData: string) => true,
  { 
    name: "sensitive-op",
    captureInput: false,
    captureOutput: false
  }
);

​
observe Options

Options for the general-purpose tracing decorator:
OptionPythonJavaScriptTypeDefaultDescription
Namenamenamestringfunction nameCustom span name
Capture Inputcapture_inputcaptureInputbooleantrueWhether to capture inputs
Capture Outputcapture_outputcaptureOutputbooleantrueWhether to capture outputs

​
Python Examples

from hmdl import observe

# Basic usage
@observe()
def helper_function(data: str) -> str:
    return data.upper()

# Custom name
@observe(name="data-processor")
def process(data: str) -> str:
    return data.upper()

# Disable capture for sensitive data
@observe(capture_input=False, capture_output=False)
def handle_credentials(username: str, password: str) -> bool:
    return authenticate(username, password)

​
JavaScript Examples

import { observe } from 'hmdl';

// Basic usage
const helperFunction = observe(
  (data: string) => data.toUpperCase(),
  { name: "helper-function" }
);

// Disable capture for sensitive data
const handleCredentials = observe(
  (username: string, password: string) => authenticate(username, password),
  { 
    name: "handle-credentials",
    captureInput: false,
    captureOutput: false
  }
);

​
Client Methods

​
flush / flushAsync

Force send all pending spans to the backend: 
# Synchronous flush
client.flush()

# Async flush
await client.flush_async()
Always call flush() before your application exits to ensure all traces are sent.

​
shutdown

Gracefully shutdown the client: 
client.shutdown()

​
Advanced Configuration

​
Batching Behavior

Spans are batched for efficient transmission:
  • Spans are collected until batch_size is reached OR flush_interval_ms elapses
  • Call flush() to immediately send all pending spans
  • Call shutdown() to flush and close the client

​
Debug Mode

Enable debug mode to see detailed logging: 
client = HeimdallClient(debug=True)
This will log:
  • Span creation events
  • Batch transmission attempts
  • Errors and retries

​
Disabling Tracing

Set enabled=False to completely disable tracing: 
client = HeimdallClient(enabled=False)
When disabled:
  • All decorators become no-ops
  • No data is sent to the backend
  • Minimal performance overhead

​
Next Steps

Environment Variables

Configure using environment variables.

Tracing Overview

Learn how tracing works.