Skip to content

auto_instrument()

Automatically patches all installed LLM libraries to emit OpenInference-compatible spans. Libraries that are not installed are silently skipped.

Signature

def auto_instrument(
    tracer_provider: TracerProvider | None = None,
    suppress_errors: bool = True,
    include_libraries: list[str] | None = None,
    exclude_libraries: list[str] | None = None,
) -> dict[str, str]

interface AutoInstrumentOptions {
    tracerProvider?: TracerProvider;
    suppressErrors?: boolean;
    includeLibraries?: string[];
    excludeLibraries?: string[];
}

function autoInstrument(options?: AutoInstrumentOptions): Record<string, InstrumentationStatus>

The TypeScript SDK also provides an async variant:

async function autoInstrumentAsync(
    options?: AutoInstrumentOptions,
): Promise<Record<string, InstrumentationStatus>>

Parameters

Parameter Type Default Description
tracer_provider TracerProvider \| None None Custom TracerProvider to use. When None, uses the global provider set by register().
suppress_errors bool True When True, instrumentation errors are logged as warnings instead of raising exceptions.
include_libraries list[str] \| None None If provided, only instrument these libraries (allowlist). Library names must match the names in the Supported Libraries table.
exclude_libraries list[str] \| None None If provided, skip these libraries (blocklist).

All parameters are keyword-only (enforced by *).

include_libraries vs exclude_libraries

These parameters are mutually exclusive in practice. If include_libraries is set, libraries not in the list are simply not attempted (they do not appear in the results at all). If exclude_libraries is set, excluded libraries appear in results with status "excluded".

Returns

dict[str, str] -- A dictionary mapping each library name to its instrumentation status.

Status Values

Status Meaning
"success" Library was found and successfully instrumented.
"not_installed" The OpenInference instrumentor package for this library is not installed.
"already_instrumented" Library was already instrumented (e.g., by a previous call).
"error" Instrumentation was attempted but failed. Check logs for details.
"excluded" Library was skipped because it is in exclude_libraries.

Supported Libraries

auto_instrument() supports the following 15 frameworks via OpenInference:

Library Name Instrumentor Package Description
openai openinference-instrumentation-openai OpenAI SDK
llamaindex openinference-instrumentation-llama-index LlamaIndex
langchain openinference-instrumentation-langchain LangChain
google-genai openinference-instrumentation-google-generativeai Google Generative AI (Gemini)
vertexai openinference-instrumentation-vertexai Google Vertex AI
bedrock openinference-instrumentation-bedrock AWS Bedrock
anthropic openinference-instrumentation-anthropic Anthropic Claude
mistralai openinference-instrumentation-mistralai Mistral AI
groq openinference-instrumentation-groq Groq
litellm openinference-instrumentation-litellm liteLLM
dspy openinference-instrumentation-dspy DSPy
crewai openinference-instrumentation-crewai CrewAI
haystack openinference-instrumentation-haystack Haystack
instructor openinference-instrumentation-instructor Instructor
guardrails openinference-instrumentation-guardrails Guardrails

Install Extras

The Coalex SDK provides install extras to pull in the correct OpenInference instrumentor packages:

# All supported frameworks
pip install coalex[auto-instrument]

# Individual frameworks
pip install coalex[openai]
pip install coalex[langchain]
pip install coalex[llamaindex]
pip install coalex[google-genai]
pip install coalex[vertexai]
pip install coalex[bedrock]
pip install coalex[anthropic]

# Multiple frameworks
pip install coalex[openai,langchain]

Install the OpenInference instrumentor packages alongside the SDK:

# OpenAI
npm install @coalex-ai/sdk @arizeai/openinference-instrumentation-openai

# LangChain
npm install @coalex-ai/sdk @arizeai/openinference-instrumentation-langchain

# Anthropic
npm install @coalex-ai/sdk @arizeai/openinference-instrumentation-anthropic

# Multiple frameworks
npm install @coalex-ai/sdk \
    @arizeai/openinference-instrumentation-openai \
    @arizeai/openinference-instrumentation-langchain

Minimal installs for production

In production, prefer installing only the extras you need. The auto-instrument extra pulls in instrumentors for OpenAI, LangChain, LlamaIndex, Vertex AI, Bedrock, and Anthropic -- which may be more than you use.

Examples

Instrument everything available

import coalex

coalex.register(api_key="your-key")

results = coalex.auto_instrument()
print(results)
# {
#     "openai": "success",
#     "llamaindex": "not_installed",
#     "langchain": "not_installed",
#     "vertexai": "not_installed",
#     "bedrock": "not_installed",
#     "anthropic": "success",
#     "mistralai": "not_installed",
#     "groq": "not_installed",
#     "litellm": "not_installed",
#     "dspy": "not_installed",
#     "crewai": "not_installed",
#     "haystack": "not_installed",
#     "instructor": "not_installed",
#     "guardrails": "not_installed",
# }

import { register, autoInstrument } from "@coalex-ai/sdk";

register({ apiKey: "your-key" });

const results = autoInstrument();
console.log(results);
// {
//     openai: "success",
//     langchain: "not_installed",
//     anthropic: "not_installed",
// }

Allowlist specific libraries

results = coalex.auto_instrument(include_libraries=["openai", "anthropic"])
# Only OpenAI and Anthropic are attempted; others are not in the results.

const results = autoInstrument({ includeLibraries: ["openai", "anthropic"] });
// Only OpenAI and Anthropic are attempted; others are not in the results.

Exclude a library

results = coalex.auto_instrument(exclude_libraries=["guardrails"])
# All libraries attempted except guardrails.
# results["guardrails"] == "excluded"

const results = autoInstrument({ excludeLibraries: ["anthropic"] });
// All libraries attempted except anthropic.
// results.anthropic === "excluded"

Custom TracerProvider

from opentelemetry.sdk.trace import TracerProvider

custom_provider = TracerProvider()
# ... configure your own processors and exporters ...

results = coalex.auto_instrument(tracer_provider=custom_provider)

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

const customProvider = new NodeTracerProvider();
// ... configure your own processors and exporters ...

const results = autoInstrument({ tracerProvider: customProvider });

Convenience Functions

For cases where you only want to instrument a single library, the SDK provides convenience functions. Each returns True on success and False on failure.

import coalex

coalex.instrument_openai()        # -> bool
coalex.instrument_langchain()     # -> bool
coalex.instrument_llamaindex()    # -> bool
coalex.instrument_google_genai()  # -> bool
coalex.instrument_vertexai()      # -> bool
coalex.instrument_bedrock()       # -> bool
coalex.instrument_anthropic()     # -> bool

All convenience functions accept an optional tracer_provider parameter:

coalex.instrument_openai(tracer_provider=my_provider)

import { instrumentOpenAI, instrumentLangChain, instrumentAnthropic } from "@coalex-ai/sdk";

instrumentOpenAI();       // -> boolean
instrumentLangChain();    // -> boolean
instrumentAnthropic();    // -> boolean

All convenience functions accept an optional tracerProvider parameter:

instrumentOpenAI(myProvider);

Notes

  • auto_instrument() should be called after register() so the global TracerProvider is already configured. If called without register() and without a tracer_provider argument, instrumented libraries use the default no-op provider.
  • Calling auto_instrument() multiple times is safe -- already-instrumented libraries return "already_instrumented".
  • Python: The function is synchronous and returns immediately after patching.
  • TypeScript: Use autoInstrumentAsync() in ESM projects where require() is not available. The sync autoInstrument() variant uses require() internally and may not work in pure ESM environments.
  • For custom pipeline steps that are not covered by auto-instrumentation (e.g., custom retrievers, rerankers), use the extension decorators.

API Reference

coalex.auto_instrument

Auto-instrumentation for popular LLM frameworks using OpenInference.

Functions

auto_instrument 

auto_instrument(
    tracer_provider: TracerProvider | None = None,
    suppress_errors: bool = True,
    include_libraries: list[str] | None = None,
    exclude_libraries: list[str] | None = None,
) -> dict[str, str]

Automatically instrument all available LLM libraries using OpenInference.

Only libraries actually installed are instrumented — missing libraries are silently skipped.

Parameters:

Name Type Description Default
tracer_provider TracerProvider | None

TracerProvider to use (defaults to global provider).

 None
suppress_errors bool

If True, log errors instead of raising (default: True).

 True
include_libraries list[str] | None

If provided, only instrument these libraries.

 None
exclude_libraries list[str] | None

If provided, skip these libraries.

 None

Returns:

Type Description
dict[str, str]

Dictionary mapping library name to instrumentation status
dict[str, str]

("success", "not_installed", "already_instrumented", "error", "excluded").
Source code in coalex/auto_instrument.py 
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def auto_instrument(
    tracer_provider: TracerProvider | None = None,
    suppress_errors: bool = True,
    include_libraries: list[str] | None = None,
    exclude_libraries: list[str] | None = None,
) -> dict[str, str]:
    """Automatically instrument all available LLM libraries using OpenInference.

    Only libraries actually installed are instrumented — missing libraries
    are silently skipped.

    Args:
        tracer_provider: TracerProvider to use (defaults to global provider).
        suppress_errors: If True, log errors instead of raising (default: True).
        include_libraries: If provided, only instrument these libraries.
        exclude_libraries: If provided, skip these libraries.

    Returns:
        Dictionary mapping library name to instrumentation status
        ("success", "not_installed", "already_instrumented", "error", "excluded").
    """
    results: dict[str, str] = {}

    for config in INSTRUMENTORS:
        lib_name = config["name"]

        if include_libraries and lib_name not in include_libraries:
            continue
        if exclude_libraries and lib_name in exclude_libraries:
            results[lib_name] = "excluded"
            continue

        results[lib_name] = _instrument_library(
            config=config,
            tracer_provider=tracer_provider,
            suppress_errors=suppress_errors,
        )

    success_count = sum(1 for v in results.values() if v == "success")
    total_attempted = sum(1 for v in results.values() if v != "excluded")

    if success_count > 0:
        successful_libs = [k for k, v in results.items() if v == "success"]
        logger.info(
            f"Auto-instrumentation complete: {success_count}/{total_attempted} libraries instrumented "
            f"({', '.join(successful_libs)})"
        )
    else:
        logger.info(
            "Auto-instrumentation complete: no libraries were instrumented. "
            "Install OpenInference packages to enable auto-instrumentation: "
            "pip install 'coalex[auto-instrument]'"
        )

    logger.debug(f"Full instrumentation results: {results}")
    return results

instrument_openai 

instrument_openai(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument OpenAI SDK specifically.

Source code in coalex/auto_instrument.py 
229
230
231
def instrument_openai(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument OpenAI SDK specifically."""
    return _convenience_instrument("openai", tracer_provider)

instrument_llamaindex 

instrument_llamaindex(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument LlamaIndex specifically.

Source code in coalex/auto_instrument.py 
234
235
236
def instrument_llamaindex(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument LlamaIndex specifically."""
    return _convenience_instrument("llamaindex", tracer_provider)

instrument_langchain 

instrument_langchain(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument LangChain specifically.

Source code in coalex/auto_instrument.py 
239
240
241
def instrument_langchain(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument LangChain specifically."""
    return _convenience_instrument("langchain", tracer_provider)

instrument_google_genai 

instrument_google_genai(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument Google GenAI (google-genai SDK) specifically.

Source code in coalex/auto_instrument.py 
244
245
246
def instrument_google_genai(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument Google GenAI (google-genai SDK) specifically."""
    return _convenience_instrument("google_genai", tracer_provider)

instrument_vertexai 

instrument_vertexai(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument Google VertexAI specifically.

Source code in coalex/auto_instrument.py 
249
250
251
def instrument_vertexai(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument Google VertexAI specifically."""
    return _convenience_instrument("vertexai", tracer_provider)

instrument_bedrock 

instrument_bedrock(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument AWS Bedrock specifically.

Source code in coalex/auto_instrument.py 
254
255
256
def instrument_bedrock(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument AWS Bedrock specifically."""
    return _convenience_instrument("bedrock", tracer_provider)

instrument_anthropic 

instrument_anthropic(
    tracer_provider: TracerProvider | None = None,
) -> bool

Instrument Anthropic Claude specifically.

Source code in coalex/auto_instrument.py 
259
260
261
def instrument_anthropic(tracer_provider: TracerProvider | None = None) -> bool:
    """Instrument Anthropic Claude specifically."""
    return _convenience_instrument("anthropic", tracer_provider)