OpenSRE Documentation

repository·main·Indexed 27 days ago

https://github.com/tracer-cloud/opensre

An open-source framework for building, training, and evaluating AI SRE agents for automated incident investigation and root cause analysis. OpenSRE enables agents to connect to observability tools like Slack, Grafana, and Datadog to investigate production failures. The project includes a provider-agnostic state management system, a benchmark suite for synthetic failure scenarios, and a Guardrails system to redact or block sensitive information in LLM calls.

Tokens
186.5K
Snippets
508
Records
1.3K
Agent score
95%

What's inside OpenSRE

  1. Overview of Tracer/collect

    main

    Tracer/collect is a core data collection daemon designed for Linux hosts. It provides low-overhead, high-fidelity observability for scientific and cloud-based high-compute workflows by capturing execution signals directly from the operating system kernel.

    Key characteristics:

    • Framework-agnostic: Works with any workflow engine, scheduler, language, or container runtime.
    • Safe and efficient: Uses eBPF kernel tracing without requiring code changes or modifying system binaries.
    • Actionable: Produces telemetry describing what ran, where it ran, and how resources were consumed.
  2. Overview of Tracer Architecture

    main

    Tracer is a multi-layered system designed to provide visibility into execution behavior in compute-intensive environments without requiring application code changes or workload modifications. It operates through three primary components:

    • Tracer/collect: An open-source eBPF agent that gathers execution signals directly from the host-layer (Linux kernel).
    • Tracer/datalake: A shared execution view that aggregates signals across different pipelines and environments.
    • Tracer/tune and Tracer/sweep: Downstream products that consume the execution signal to perform optimization and waste detection.

    The system is non-intrusive, meaning it does not require container restarts or application instrumentation.

  3. Overview of Platform runtime services

    main

    The platform/ directory contains shared runtime services that operate outside the user-facing application package and the core agent harness loop. These services handle side effects such as telemetry, audit logging, authentication, and safety guardrails.

    Key subsystems include:

    • auth/: Runtime authentication and identity checks.
    • analytics/: Product and runtime analytics.
    • common/: Small shared helpers.
    • deployment/: EC2 provisioning (includes aws/ primitives, deploy.py, and destroy.py).
    • notifications/: Notification delivery transports and channel-specific senders.
    • observability/: Logging, tracing, progress, debug output, and runtime display ports.
    • masking/: Reversible masking and identifier normalization.
    • scheduler/: Cron-driven scheduled deliveries, task persistence, and execution deduplication.
    • sandbox/: Constrained execution environments.
    • guardrails/: Minimal runtime safety checks outside the core agent loop.
  4. Overview of Tracer Agent Architecture

    main
    The Tracer Agent is a lightweight process designed to run on compute nodes to observe pipeline execution. Unlike traditional monitoring systems that require application-level hooks or SDKs (which necessitate code changes and introduce overhead), the Tracer Agent leverages eBPF (Extended Berkeley Packet Filter) technology. This allows it to monitor workloads directly from the Linux kernel, making it suitable for scientific workloads involving thousands of short-lived processes and complex binaries (e.g., BLAST, BWA, GATK, TensorFlow) with minimal overhead.
  5. Understand Tracer's performance and security boundaries

    main

    Performance

    Tracer's eBPF-based collection is designed for low overhead:

    • Low latency: Probes execute in kernel space.
    • Efficient filtering: Event filtering occurs at the source to reduce data volume.
    • Scalability: Maintains low overhead even with many short-lived processes.

    Security Boundaries

    Tracer is an observability tool and does not:

    • Modify application behavior.
    • Control execution or scheduling.
    • Start, stop, or change resources.
    • Replace IAM, RBAC, or cloud security controls.
  6. Understand the relationship between Tracer and Datadog

    main

    Tracer and Datadog are complementary tools rather than competitors.

    • Datadog is a general-purpose observability platform for metrics, logs, traces, dashboards, and alerting across infrastructure and applications. It organizes telemetry around services, hosts, and applications.
    • Tracer provides execution-aware insight by observing how tasks, tools, and processes actually execute at runtime. It organizes behavior by pipeline, run, and execution unit.

    Use Tracer alongside Datadog when you need to understand pipeline behavior beyond service-level telemetry, diagnose performance issues in short-lived or nested execution, or attribute resource usage and cost to specific workflows or tools.

  7. Identify Tracer's product boundaries and limitations

    main

    Tracer is an observation tool and is intentionally scoped to avoid interfering with workloads.

    Tracer does NOT:

    • Modify application behavior.
    • Control execution or scheduling.
    • Start, stop, or terminate workloads.
    • Replace IAM, RBAC, or cloud security controls.

    Tracer operates strictly within the boundaries enforced by the operating system, container runtime, and cloud provider.

  8. Understand the OpenSRE documentation structure

    main

    The documentation is built using Mintlify and follows this structure:

    • docs.json: Configuration file for navigation and theme settings.
    • *.mdx: Documentation pages written in MDX (Markdown with JSX).
    • images/: Directory for static assets like screenshots and diagrams.
    • snippets/: Directory for reusable content blocks.
  9. Understand OpenSRE EC2 deployment behavior

    main

    Stack Composition

    The make deploy command creates a stack named opensre-ec2 containing:

    • ECR Repository: Named opensre.
    • EC2 Instance: A t2.micro instance in the account's default VPC (public subnet).
    • Security Group: Allows inbound TCP 8000 for the web component.
    • IAM Instance Profile: Provides permissions for ECR pulling, SSM, and Bedrock (if applicable).
    • Containers:
      • opensre-web: Runs in MODE=web on port 8000.
      • opensre-gateway: Runs in MODE=gateway using Telegram long-polling.

    Outputs

    Deployment metadata is saved to ~/.opensre/deployments/opensre-ec2.json. This includes the InstanceId, PublicIpAddress, and ImageUri.

    Redeployment and Safety

    • Auto-destroy: If a stack already exists (detected via the local JSON file or EC2 tags tracer:stack=opensre-ec2), make deploy will automatically destroy the old stack before provisioning a new one.
    • Abort Option: To prevent accidental destruction, set the environment variable OPENSRE_DEPLOY_ABORT_IF_EXISTS=1 to make the deployment fail if a stack is already present.