Volcengine TLS Bootstrap

A Python bootstrap utility for automatically installing and configuring Volcengine's OpenTelemetry instrumentation packages for LLM applications. This package provides a command-line interface similar to opentelemetry-instrumentation for seamless integration with Volcengine TLS (Torch Log Service).

Overview

The volcengine-tls-bootstrap package serves as a centralized installer for Volcengine's OpenTelemetry instrumentation ecosystem, specifically designed for:

• LangChain applications - Automatic instrumentation of LangChain LLM calls
• OpenAI integrations - Tracing OpenAI API calls and completions
• General Python services - Comprehensive observability for distributed systems

Installation

pip install --upgrade volcengine-tls-bootstrap

For ByteDance internal PyPI, install the identical Bootstrap implementation under its internal distribution name instead. The import namespace and the CLI below remain unchanged:

pip install --index-url https://bytedpypi.byted.org/repository/pypi-group/simple \
  --upgrade byted-tls-bootstrap

Quick Start

Install the TLS runtime bundle

volcengine-tls-bootstrap -a install

Install a verified runtime version

volcengine-tls-bootstrap -a install -v <validated-runtime-version>

volcengine-tls-bootstrap is the only package that users install from PyPI. -a install downloads the versioned Python runtime bundle from the TLS TOS artifact repository and installs the wheel set contained in that bundle. Pin the bootstrap and runtime versions for production; do not separately install instrumentation or exporter wheels from PyPI, and do not upgrade dependencies during container startup. Every remote runtime archive must have a colocated <archive>.sha256 sidecar. Bootstrap verifies it before extraction; for a local archive pass --agent-sha256 (or set PYTHON_AGENT_SHA256).

The normal remote install requires neither a Runtime version nor a SHA256 from the application developer:

volcengine-tls-bootstrap -a install

It resolves the published latest archive and downloads its colocated sidecar automatically. For a reproducible image build, pin the published Runtime with -v <runtime-version>; its sidecar is still discovered automatically. --agent-sha256 is required only for a local archive, or may be supplied by a build system as an additional policy check.

Install Into a Non-standard Directory

When -t (or PIPPATH) is used, pip --target does not automatically expose installed modules or console scripts to the application. Bootstrap writes a helper after installation; source it in the same process that starts the application:

volcengine-tls-bootstrap -a install -v <validated-runtime-version> -t /opt/tls-agent
source /opt/tls-agent/activate-volcengine-tls.sh
volcengine-tls-instrument --check
volcengine-tls-instrument python app.py

For a locally downloaded artifact:

export PYTHON_AGENT_SHA256=<sha256-of-volcengine-opentelemetry-python-agent.tar.gz>
volcengine-tls-bootstrap -a install --local \
  -u /path/to/volcengine-opentelemetry-python-agent.tar.gz \
  --agent-sha256 "$PYTHON_AGENT_SHA256" \
  -t /opt/tls-agent

--local accepts either the conventional archive name in the current working directory or an explicit archive path through -u. The target directory is isolated; it does not install runtime packages into the system Python.

LangChain Compatibility

The runtime archive supplies fallback dependencies for a clean environment; the application's own LangChain dependencies remain authoritative. Current LangChain 1.3.16 requires langchain-core>=1.6.0, so use a runtime version validated with that dependency train. Do not replace one wheel inside an existing archive: rebuild and install the complete versioned archive and its checksum sidecar instead.

For a legacy LangChain 0.3 application, install the runtime into a target directory and source activate-volcengine-tls.sh. The helper keeps the application site-packages ahead of the runtime fallback wheels, so the application continues using its own compatible LangChain core.

Commands

The bootstrap utility supports the following operations:

• install - Download and install the versioned Volcengine OpenTelemetry runtime bundle (default)
• uninstall - Remove all installed instrumentation packages
• requirements - Install instrumentation packages based on detected dependencies

Configuration

The installer automatically configures:

• OpenTelemetry SDK initialization
• TLS exporter configuration
• Context propagation settings
• Auto-instrumentation hooks

Privacy Notice

By default, this package will record prompts and completions as span attributes in your traces. This behavior can be configured through environment variables or manual instrumentation settings.