AGENTS.md - Streams Repository

Repository Overview

This repository contains the Sentry Streaming Platform. The Streaming Platform provides the infrastructure and the runtime to build and run Kafka based streaming stateful and stateless streaming applications.

Repository Structure

The repository is organized into two main Python packages:

• sentry_streams/ - The core streaming platform implementation (hybrid Rust/Python package)

  • See sentry_streams/AGENTS.md for package-specific development instructions

• sentry_streams_k8s/ - Kubernetes integration and deployment automation for Sentry Streams (pure Python package)

  • See sentry_streams_k8s/AGENTS.md for package-specific development instructions

Architecture documents

Overall structure of the streaming platform is in the README. It contains links to the specific module.

The architecture of the platform itself — subsystems, decisions, invariants, guarantees and known debt — is in sentry_streams/docs/architecture.

Other Directories

• platforms/ - Docker and deployment configurations
• scripts/ - Utility scripts for development and deployment

Makefile Commands

The root Makefile provides commands for common development tasks across both packages:

Setup and Installation

make install-dev

Installs development dependencies for all packages using uv. This will:

• Install uv package manager if not present
• Set up virtual environments for sentry_streams and sentry_streams_k8s

make install-pre-commit-hook

Installs pre-commit hooks for code quality checks.

make reset

Removes all build artifacts and virtual environments for a clean slate.

Testing

make tests-streams

Runs Python tests for the sentry_streams package.

make tests-integration

Runs integration tests for sentry_streams.

make tests-rust-streams

Runs Rust tests for the sentry_streams package.

make tests-k8s

Runs tests for the sentry_streams_k8s package.

Type Checking

make typecheck

Runs mypy type checking on both packages. This will:

• Build Rust modules needed for type checking
• Run strict type checking on sentry_streams
• Run strict type checking on sentry_streams_k8s

Building and Documentation

make build-streams

Builds the sentry_streams wheel package.

make build-streams-k8s

Builds the sentry_streams_k8s wheel package.

make docs

Builds the Sphinx documentation for the streaming platform.

Development Prerequisites

• Python 3.11+
• Rust toolchain (for sentry_streams development)
• uv package manager (automatically installed by make install-dev)
• direnv (recommended for automatic environment setup)

Working with Individual Packages

For detailed development instructions specific to each package, including virtual environment requirements, testing, and type checking, see the AGENTS.md files in each package directory:

• sentry_streams/AGENTS.md

Additional Notes

• The repository uses direnv for automatic environment setup. Run direnv allow when prompted.
• If encountering CMake errors, the .envrc should set CMAKE_POLICY_VERSION_MINIMUM=3.5 automatically.
• For GCP interactions, run gcloud auth application-default login.
• Documentation is available at: https://getsentry.github.io/streams/