Overview

This guide explains how to integrate Permitech with OpenTelemetry and OpenInference for comprehensive observability and tracing of your AI/ML workflows using industry-standard tools.

OpenTelemetry

The first step is to configure OpenTelemetry.

Installation

Add the Permitech SDK and OpenTelemetry packages to your project:

pip install opentelemetry-api opentelemetry-sdk \
            opentelemetry-exporter-otlp

npm install permitech \
      @opentelemetry/sdk-trace-node \
      @opentelemetry/exporter-trace-otlp-proto

For Python, the opentelemetry-api and opentelemetry-sdk packages provide the core OpenTelemetry functionality. The opentelemetry-exporter-otlp package enables sending traces to Permitech’s OTLP endpoint.For TypeScript, the permitech package includes the PermitechSpanProcessor which handles OTLP export configuration automatically. The @opentelemetry/sdk-trace-node and @opentelemetry/exporter-trace-otlp-proto packages are required peer dependencies.

Create environment variables for your Permitech settings

Set environment variables for your Permitech settings, for example in a .env file. These environment variables are consumed by the PermitechSpanProcessor to authenticate and route traces to the correct Permitech Project and Log stream:

# Your Permitech API key
PERMITECH_API_KEY="your-permitech-api-key"

# Your Permitech project name
PERMITECH_PROJECT="your-permitech-project-name"

# The name of the Log stream you want to use for logging
PERMITECH_LOG_STREAM="your-permitech-log-stream "

# Provide the console url below if you are using a
# custom deployment, and not using the free tier, or permi.tech.
# This will look something like “console.permitech.yourcompany.com”.
# PERMITECH_CONSOLE_URL="your-permitech-console-url"

Self-hosted deployments: Set the OTel endpoint

Skip this step if you are using Permitech Cloud.

The OTel endpoint is different from Permitech’s regular API endpoint and is specifically designed to receive telemetry data in the OTLP format.If you are using:

Permitech Cloud at permi.tech, then you don’t need to provide a custom OTel endpoint. The default endpoint https://permi.tech/api/otel/traces will be used automatically.
A self-hosted Permitech deployment, replace the https://permi.tech/api/otel/traces endpoint with your deployment URL. The format of this URL is based on your console URL, replacing console with api and appending /otel/traces.

For example:

if your console URL is https://console.permitech.example.com, the OTel endpoint would be https://api.permitech.example.com/otel/traces
if your console URL is https://console-permitech.apps.mycompany.com, the OTel endpoint would be https://api-permitech.apps.mycompany.com/otel/traces

The convention is to store this in the PERMITECH_CONSOLE_URL environment variable. For example:

os.environ["PERMITECH_CONSOLE_URL"] = "https://console.permitech.example.com"

process.env.PERMITECH_CONSOLE_URL = "https://console.permitech.example.com";

Initialize and create the Permitech span processor

The PermitechSpanProcessor automatically configures authentication and metadata using your environment variables. It also:

Auto-builds OTLP headers using your Permitech credentials
Configures the correct OTLP trace endpoint
Registers a batch span processor that exports traces to Permitech

from permitech import otel  

# PermitechSpanProcessor (no manual OTLP config required) loads the env vars for 
# the Permitech API key, Project, and Log stream. Make sure to set them first. 
permitech_span_processor = otel.PermitechSpanProcessor(
    # Optional parameters if not set, uses env var
    # project=os.environ["PERMITECH_PROJECT"], 
    # logstream=os.environ.get("PERMITECH_LOG_STREAM"),  
)

import { PermitechSpanProcessor } from 'permitech';

// PermitechSpanProcessor (no manual OTLP config required) loads the env vars for
// the Permitech API key, Project, and Log stream. Make sure to set them first.
const processor = new PermitechSpanProcessor({
    // Optional parameters if not set, uses env var
    // project: process.env.PERMITECH_PROJECT,
    // logstream: process.env.PERMITECH_LOG_STREAM,
});

The span processor can now be registered with an OTel trace provider.

from opentelemetry.sdk import trace as trace_sdk

tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(permitech_span_processor)

import { addPermitechSpanProcessor } from 'permitech';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';

const provider = new NodeTracerProvider();
addPermitechSpanProcessor(provider, processor);
provider.register();

You can now use this trace provider either using a framework that supports OTel directly, or via OpenInference.

OpenInference

OpenInference instrumentors are currently available for Python only. For TypeScript/Node.js applications, use framework-specific OTel integrations such as Vercel AI SDK or Mastra.

You can enable automatic tracing for your framework and LLM operations using OpenInference instrumentors. These add AI-specific semantic conventions to your traces. For example, to instrument LangChain and OpenAI start by adding the relevant OpenInference packages:

pip install openinference-instrumentation-langchain \
            openinference-instrumentation-openai

Now you can add the instrumentation to your code, using the OTel trace provider.

from openinference.instrumentation.langgraph import (
    LangGraphInstrumentor
)
from openinference.instrumentation.openai import (
    OpenAIInstrumentor
)

LangGraphInstrumentor().instrument(tracer_provider=tracer_provider)
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

OpenInference adds:

Automatic capture of LLM calls, token usage, and model performance metrics
AI-specific span attributes like gen_ai.request.model, gen_ai.response.content, and gen_ai.usage.*
Semantic conventions that make your traces more meaningful in Permitech’s dashboard
Framework-specific instrumentation for LangGraph workflows and OpenAI API calls

Once OpenTelemetry and OpenInference is set up your application will automatically capture and send observability data to Permitech with every run, providing complete traces of your AI workflows, detailed LLM call breakdowns, and performance insights organized by project and Log stream. For a detailed example of using OpenTelemetry and OpenInference with LangGraph, see the Log with OpenTelemetry, LangGraph, and OpenAI how-to guide.

Next steps

Learn how to integrate with some popular frameworks using OpenTelemetry and OpenInference.

Google ADK

Learn how to integrate a Google ADK project with Permitech using OpenTelemetry and OpenInference.

Strands Agents

Learn how to integrate a Strands Agents project with Permitech using OpenTelemetry.

Vercel AI SDK

Learn how to integrate a Vercel AI SDK project with Permitech using OpenTelemetry.

Mastra

Learn how to integrate a Mastra project with Permitech using OpenTelemetry.

Get Started

Observability

Evaluation Metrics

Signals

AI Assistant

Luna Studio

Experiments

Agent Control

Annotations

Integrations

Security

References

Overview

OpenTelemetry

OpenInference

Next steps

Google ADK

Strands Agents

Vercel AI SDK

Mastra

​OpenTelemetry

​OpenInference

​Next steps

Google ADK

Strands Agents

Vercel AI SDK

Mastra

OpenTelemetry

OpenInference

Next steps