README.md

Documentation for developers

This directory contains developer documentation and repository-hosted design references. It also contains the operator-facing Config migration guide linked from the repository README. General setup documentation lives on the OpenTelemetry website.

Table Of Contents

• Pipeline Map: explanation of pipeline map.
• Config v1 to v2 migration: operator guide for migrating and validating standalone and Collector receiver configurations.
• Profiling: how to profile OBI.
• Features: features supported by OBI.
• Context Propagation Architecture: how OpenTelemetry context propagation works in the eBPF instrumentation.
• gRPC Context Propagation: HTTP/2 and gRPC context propagation via sk_msg HPACK injection (TCP options are not used).
• Node.js manual spans: capturing @opentelemetry/api spans when no Node.js SDK is registered.
• Protocols: documentation about supported protocols.
• Java TLS IOCTL Security Notes: rationale for the localized Java TLS ioctl hardening and why OBI keeps this fix in java_tls.c.
• AI Tooling: recommendations for configuring agent tooling for this repository.
• BPF print format: it explains a uniform standard for all BPF print debug statements across the project.
• Dependency Integrity Policy: required dependency pinning and verification rules for Dockerfiles.
• Python asyncio and uvloop Context Propagation: architecture and implementation of Python async context propagation for asyncio workloads, including applications running on uvloop.
• Go Channel Span Links: receiver-side span links for supported Go channel handoffs.
• Trace-Profile Correlation: standard communication channel for correlating profiles to OBI traces.
• Kubernetes Metadata Cache Service (k8s-cache): what the standalone metadata cache service is, why it exists, and how to deploy it alongside OBI.
• Metrics: how the NetO11y, AppO11y, and StatsO11y pipelines turn eBPF events into exported metrics, and where to edit when adding a new one.
• BPF Metrics Collection: how OBI discovers all existing supported probes and LRU hash maps on the host and reports their metrics.
• Runtime Metrics: developer notes for the application_runtime feature and per-runtime coverage.