OCELOT

OpenTelemetry Collector Extension Layer Optimization Toolkit

Build custom, optimized AWS Lambda Extension Layers for the OpenTelemetry Collector with ease. Ocelot simplifies adding specific observability components, integrating with the upstream OpenTelemetry Lambda project via an "overlay" strategy to avoid forking.

Warning

Alpha Software Notice: Ocelot is currently in alpha development. While functional and actively used, the CLI, APIs, and configuration format may change between versions. We welcome feedback and contributions.

Why Ocelot?

Building custom OpenTelemetry layers for AWS Lambda often requires forking the upstream open-telemetry/opentelemetry-lambda repository, leading to maintenance overhead. Ocelot solves this by allowing you to define custom "distributions" of the collector, building only what you need.

Quick Example

Define a custom distribution in config/distributions.yaml:

distributions:
  my-custom-layer:
    description: "A minimal layer with a ClickHouse exporter"
    base: minimal
    build-tags:
      - "lambdacomponents.exporter.clickhouse"

Build and publish your custom layer with a single command:

uv run tools/ocelot.py --distribution my-custom-layer

Ocelot automatically:

• ✅ Clones the upstream OpenTelemetry Lambda repository
• ✅ Applies your custom components as an overlay
• ✅ Builds a lean collector binary with only the components you need
• ✅ Packages it as a Lambda layer and publishes it to your AWS account

Key Features

• Overlay Strategy: Avoid forking the upstream repository, reducing maintenance overhead.
• Flexible Distributions: Build tailored collector layers with pre-defined or custom component sets.
• Multiple Build Options: Use pre-built layers, build locally, or set up a fully automated pipeline in your own fork.
• Automated Publishing: Securely publish layers to multiple AWS regions and architectures using GitHub Actions and OIDC.
• Customizable Configurations: Package custom OpenTelemetry Collector config.yaml files within your layers.

How to Get Started

There are three primary ways to get and use Ocelot layers:

1. Use Pre-built Layers (Easiest): Find layers for various distributions in the Releases section.
2. Local Build: Compile and publish layers directly from your local machine. See the Quickstart Guide to begin.
3. Fork and Use GitHub Actions: Set up your own automated build system. See the guide on Setting Up Your Fork.

Prerequisites for Local Build

• Go (latest stable): For compiling the collector.
• uv: A fast Python package manager for running the build scripts.
• AWS Credentials: Configured for programmatic access to publish layers.

Documentation

📖 Complete Documentation →

Our comprehensive documentation includes:

• Quickstart Guide: Build your first custom layer in minutes.
• Architecture Deep Dive: Understand the overlay strategy.
• Component & Distribution Guides: Learn how to add custom components.
• CLI Reference: All command-line options and usage.
• Contributing Guide: Learn how to contribute to Ocelot.

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on the development workflow.

License

This project is licensed under the MIT License. See the LICENSE file for full details.