🔭 OpenSearch Observability Stack
Observability Stack is an open-source stack designed for modern distributed systems. Built on OpenTelemetry, OpenSearch, and Prometheus, Observability Stack provides a complete, pre-configured infrastructure for monitoring microservices, web applications, and AI agents—with first-class support for agent observability through OpenTelemetry Gen-AI Semantic Conventions.
Components
- OpenTelemetry Collector: Receives OTLP data and routes it to appropriate backends
- Data Prepper: Transforms and enriches logs and traces before storage
- OpenSearch: Stores and indexes logs and traces for search and analysis
- Prometheus: Stores time-series metrics data
- OpenSearch Dashboards: Provides web-based visualization and exploration
- PPL (Piped Processing Language): Native query language for logs and traces — pipe-based, human-readable, 50+ commands
See it in action
https://github.com/user-attachments/assets/bef4c3ad-c64d-4db8-96f5-9ffd26bd0b03
🚀 Quickstart
Option 1: One-Command Install (Recommended)
Use our interactive installer for the best experience:
curl -fsSL https://raw.githubusercontent.com/opensearch-project/observability-stack/main/install.sh | bash
The installer will:
- ✅ Check system requirements (Docker/Finch, Git, memory)
- 🎨 Guide you through configuration with a beautiful TUI
- 📦 Pull and start all services automatically
- 🔐 Optionally set custom OpenSearch credentials
- 📊 Display credentials and access points
Installer flags:
| Flag | Description |
|---|
--simulate | Preview the installer output without actually installing |
--skip-pull | Skip pulling container images (uses cached images) |
--help | Show help message |
To run the installer locally (e.g. after cloning):
./install.sh # Full install
./install.sh --simulate # Dry run
./install.sh --skip-pull # Skip image pulls (useful for re-installs)
Installation takes 8-15 minutes. After completion, access:
Option 2: Manual Setup
To get started manually with Docker Compose:
1️⃣ Clone the repository:
git clone https://github.com/opensearch-project/observability-stack.git
cd observability-stack
Optional: Configure stack
The .env file contains all configurable parameters:
- Example services: Included by default via
INCLUDE_COMPOSE_EXAMPLES=docker-compose.examples.yml. Comment out to run only the core stack.
- OpenTelemetry Demo: Not enabled by default. Uncomment
INCLUDE_COMPOSE_OTEL_DEMO=docker-compose.otel-demo.yml to add the full OpenTelemetry Demo microservices app for realistic e-commerce telemetry (~2GB additional memory required).
See Configuration section for more details.
2️⃣ Start the stack:
docker compose up -d
This starts all services including example services (multi-agent travel planner, weather-agent, events-agent, and canary) that generate sample telemetry data.
3️⃣ View your Logs and Traces in OpenSearch Dashboards
👉 Navigate to http://localhost:5601
Username and password can be retrieved from .env file:
grep -E '^OPENSEARCH_(USER|PASSWORD)=' .env
Destroying the Stack
To stop the stack while preserving your data:
docker compose down
To stop the stack and remove all data volumes:
docker compose down -v
Instrumenting Your Agent
Observability Stack accepts telemetry data via the OpenTelemetry Protocol (OTLP) and follows the OpenTelemetry Gen-AI Semantic Conventions for standardized attribute naming and structure for AI agents.
OTLP Endpoint Configuration
The OTel Collector exposes two OTLP endpoints — choose the one that matches your SDK's protocol:
| Port | Protocol | Endpoint | Used By |
|---|
| 4317 | gRPC | http://localhost:4317 | OpenTelemetry SDK (default), most language SDKs |
| 4318 | HTTP/protobuf | http://localhost:4318 | Strands SDK (setup_otlp_exporter()), HTTP-based exporters |
