How arize-ai/openinference works
Project Type and Purpose
• This is an open-source instrumentation framework (OpenInference) that provides:
• A formal specification (in Markdown under /spec) for tracing AI/LLM applications
• A core library with shared utilities and semantic conventions
• Language-specific instrumentation packages (Python, JavaScript, Java) that implement the spec atop OpenTelemetry
• Example applications in each language demonstrating how to use the instrumentations
• CI/CD pipelines to test, build, and publish each package to its registry
High-Level Architecture Components
A. Specification Layer
• /spec directory: Markdown docs defining the OpenInference trace model and semantic conventions
• Serves as the source of truth for all downstream libraries
B. Core Libraries
• js/packages/openinference-core and python/openinference-instrumentation and java/openinference-instrumentation
• Provide shared code for managing spans, context attributes, tracer configuration, masking rules, etc.
• Depend on the Spec
C. Semantic Conventions
• js/packages/openinference-semantic-conventions, python/openinference-semantic-conventions, java/openinference-semantic-conventions
• Attribute names, resource attributes, span kinds, etc., per the spec
• Imported by core and instrumentation modules
D. Instrumentation Plugins
• Python: many sub-packages under python/instrumentation/openinference-instrumentation-*
• JavaScript: js/packages/openinference-instrumentation-* (OpenAI, LangChain, BeeAI, MCP, Vercel, Mastra)
• Java: java/instrumentation/openinference-instrumentation-* (LangChain4j, SpringAI)
• Each plugin: wraps a target SDK or framework to emit OpenInference spans
E. Examples and Demo Apps
• For each language, the examples/ folders under python/, js/examples/, java/examples/
• Complete end-to-end usage: app code <–instrumentation→ OTEL SDK <–spans→ collector
F. CI/CD and Publishing
• .github/workflows/: separate pipelines for Python (tox, pyproject), JS (pnpm, ts), Java (Gradle), release tooling
• Scripts: version-update, release-please, dependency updates (Dependabot)
• Targets: PyPI, npm registries, Maven Central, Docker (examples)
G. External Dependencies and Services
• OpenTelemetry–compatible collectors
• Arize-Phoenix or any OTEL backend for span ingestion
• Language SDK runtimes (FastAPI, Next.js, Express, Spring AI, LangChain, DSPy, LlamaIndex, etc.)
Relationships and Data Flows
• Spec → informs → Semantic Conventions → imported by → Core Libraries
• Core Libraries + Semantic Conventions → used by → Instrumentation Plugins
• Instrumentation Plugins → wrap → Target SDKs → generate → Spans
• Examples → include → Instrumentation Plugins + Target SDK code → send spans → OTEL Collector
• CI/CD Workflows → build/test → publish → Package Registries
Architectural Patterns
• Layered Architecture: Spec → Core → Plugins → Examples
• Plugin Pattern: Each SDK/framework gets its own wrapper module
• Polyglot Distribution: Same spec implemented across Python, JS, Java ecosystems
• GitOps for CI/CD: Declarative workflows driving tests and releases
Essential Elements
• Component names exactly as they appear in the file tree (e.g., openinference-core, openinference-instrumentation-openai)