Metadata-Version: 2.4
Name: volcengine-tls-bootstrap
Version: 1.0.6
Summary: Instrumentation Tools & Auto Instrumentation for OpenTelemetry Python
Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/opentelemetry-instrumentation
Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python-contrib
Author-email: OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Requires-Dist: packaging>=23.0
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.66.1
Description-Content-Type: text/markdown

# Volcengine TLS Bootstrap

[![PyPI version](https://badge.fury.io/py/volcengine-tls-bootstrap.svg)](https://badge.fury.io/py/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

```bash
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:

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

## Quick Start

### Install the TLS runtime bundle

```bash
volcengine-tls-bootstrap -a install
```

### Install a verified runtime version

```bash
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:

```bash
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:

```bash
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:

```bash
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.
