keyval/odigos-instrumentor

odigos Instrumentor服务镜像文档

镜像概述

odigos Instrumentor服务镜像是odigos可观测性平台的核心组件，专为自动为应用程序注入监控和可观测性代码而设计。该服务通过动态代码注入技术，在不修改应用源码的前提下，为应用程序添加分布式追踪、性能指标和日志收集能力，大幅简化分布式系统的可观测性配置流程。

核心功能与特性

主要功能

• 自动代码注入：无需手动修改应用代码，自动为目标应用注入可观测性工具链所需的 instrumentation 代码
• 多语言支持：兼容主流编程语言及框架（包括Java、Python、Go、Node.js等）
• 全栈可观测性：同时支持追踪（Tracing）、指标（Metrics）和日志（Logging）数据的采集
• 工具链集成：无缝对接主流可观测性后端（Prometheus、Jaeger、Grafana、OpenTelemetry Collector等）

关键特性

• 零侵入配置：通过环境变量和配置文件控制注入行为，无需改变应用部署流程
• 动态配置更新：支持运行时调整可观测性采集参数，无需重启应用
• 轻量级注入：最小化性能开销，优化注入代码的资源占用
• 容器化原生支持：专为容器环境设计，适配Kubernetes、Docker Compose等部署方式

使用场景与适用范围

典型使用场景

• 分布式微服务架构中快速部署统一的可观测性方案
• DevOps流程中集成自动化监控配置，减少人工操作
• 遗留系统的可观测性改造，无需重构应用代码
• 多语言技术栈的统一监控策略实施

适用范围

• 容器化应用部署环境（Docker、Kubernetes）
• 微服务及分布式系统
• 需要快速实现可观测性的开发/测试/生产环境
• 支持的编程语言：Java 8+、Python 3.6+、Go 1.13+、Node.js 12+

使用方法与配置说明

基本部署（Docker Run）

bash
docker run -d \
  --name odigos-instrumentor \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 访问Docker守护进程以检测目标容器
  -v /path/to/app/config:/config \               # 挂载配置文件目录
  -e TARGET_APP_PATH=/app \                      # 目标应用代码路径（容器内）
  -e INSTRUMENTATION_TYPE=full \                 # 注入类型：full/tracing/metrics/logging
  -e OTEL_COLLECTOR_URL=http://otel-collector:4317 \  # OpenTelemetry Collector地址
  odigos/instrumentor:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  odigos-instrumentor:
    image: odigos/instrumentor:latest
    container_name: odigos-instrumentor
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./instrumentor-config:/config
    environment:
      - TARGET_APP_CONTAINER_LABEL=app=my-service  # 通过标签匹配目标容器
      - LANGUAGES=java,python,go                   # 指定需要处理的编程语言
      - METRICS_EXPORT_ENABLED=true                # 启用指标导出
      - TRACING_SAMPLER_RATE=1.0                   # 追踪采样率（0.0-1.0）
      - LOG_LEVEL=info                             # 服务日志级别
    restart: unless-stopped

环境变量配置

配置文件说明

可通过挂载配置文件目录（如/config）提供更详细的自定义配置，支持JSON/YAML格式，配置项覆盖环境变量设置。示例config.yaml：

yaml
instrumentation:
  tracing:
    enabled: true
    sampler:
      type: parentbased_always_on
  metrics:
    enabled: true
    export_interval: 15s
  logging:
    enabled: true
    level: info
targets:
  containers:
    - label_selector: "app=payment-service"
      languages: ["java", "kotlin"]
exporters:
  otel_collector:
    endpoint: "http://otel-collector:4317"
    timeout: 5s

注意事项

• 确保容器具有足够权限访问Docker守护进程（如挂载/var/run/docker.sock）或目标应用文件系统
• 对生产环境使用前，建议在测试环境验证注入效果及性能影响
• 部分编程语言可能需要特定版本的运行时支持，详细兼容性列表请参考odigos官方文档
• 注入过程可能需要目标应用短暂重启（取决于注入模式），建议在维护窗口执行