Skip to content

README.md

Latest commit

 

History

History
187 lines (130 loc) · 4.65 KB

README.md

File metadata and controls

187 lines (130 loc) · 4.65 KB

Acme SDK for Python

CI PyPI version Python 3.9+

The official Python SDK for the Acme Observability Platform. Collect, export, and analyze traces, spans, and metrics from your applications with minimal configuration.

Features

  • Distributed Tracing — Capture traces and spans with full context propagation
  • Multiple Exporters — Ship data via OTLP, JSON files, or console output
  • Flexible Authentication — API key and OAuth 2.0 support
  • Batch Processing — Efficiently batch and compress telemetry data
  • Automatic Retries — Configurable retry logic with exponential backoff
  • Configuration Management — YAML/TOML config files with environment variable interpolation

Installation

pip install acme-sdk

For gRPC transport support:

pip install acme-sdk[grpc]

Quick Start

from acme_sdk import AcmeClient
from acme_sdk.models import Span, Event
from acme_sdk.exporters.otlp import OTLPExporter

# Initialize the client
client = AcmeClient(
    api_key="your-api-key",
    endpoint="https://ingest.acme-sdk.dev",
)

# Create and export a span
span = Span(
    name="process_request",
    service_name="my-service",
    duration_ms=142.5,
    attributes={"http.method": "GET", "http.status_code": 200},
)

# Export using OTLP
exporter = OTLPExporter(client=client)
exporter.export([span])

Configuration

You can configure the SDK via code, environment variables, or a config file:

from acme_sdk.config import AcmeConfig

# From environment variables
config = AcmeConfig.from_env()

# From a config file
config = AcmeConfig.from_file("acme.toml")

Environment variables:

Variable Description Default
ACME_API_KEY API key for authentication —
ACME_ENDPOINT Ingest endpoint URL https://ingest.acme-sdk.dev
ACME_TIMEOUT Request timeout in seconds 30
ACME_COMPRESSION Enable gzip compression true
ACME_BATCH_SIZE Max spans per batch 512

Exporters

The SDK ships with three built-in exporters:

OTLP Exporter

The recommended exporter for production use. Sends data via HTTP using the OpenTelemetry Protocol.

from acme_sdk.exporters.otlp import OTLPExporter

exporter = OTLPExporter(client=client, compression=True)
exporter.export(spans)

JSON File Exporter

Writes telemetry data to local JSON files. Useful for debugging and local development.

from acme_sdk.exporters.json_file import JSONFileExporter

exporter = JSONFileExporter(output_dir="./traces")
exporter.export(spans)

Console Exporter

Prints telemetry data to stdout. Great for development and debugging.

from acme_sdk.exporters.console import ConsoleExporter

exporter = ConsoleExporter(colorize=True)
exporter.export(spans)

Authentication

The SDK supports two authentication methods:

API Key

client = AcmeClient(api_key="your-api-key")

OAuth 2.0

from acme_sdk.auth import OAuthProvider

auth = OAuthProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
    token_url="https://auth.acme-sdk.dev/oauth/token",
)
client = AcmeClient(auth_provider=auth)

Documentation

Development

# Clone the repo
git clone https://github.com/acme-corp/acme-sdk-python.git
cd acme-sdk-python

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Type checking
mypy src/

Contributing

We welcome contributions! Please see our contributing guidelines and make sure to:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for any new functionality
  4. Ensure all tests pass and linting is clean
  5. Open a pull request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Support

When you recieve an error, please check the troubleshooting guide before opening an issue.