Tutorial: Add observability metrics to a CI-based analyzer

Observability metrics help you understand how CI-based security analyzers perform in production. Metrics like scan duration, exit codes, and findings count, flow through the security report artifact to GitLab’s internal event tracking system.

For an implementation example, see Secret Detection metrics.

Architecture

flowchart LR
    A[CI Analyzer] --> B[Security Report]
    B --> C[Post-analyzer]
    C --> D[Internal Event Tracking]
    D --> E[Snowflake]

1. The CI analyzer collects metrics during the scan and writes them to the security report artifact.
2. The post-analyzer processes the report and extracts observability events.
3. Allowed events are sent to the internal event tracking system.
4. Events are stored in Snowflake for analysis and dashboards.

Design considerations

The observability system uses a decentralized events pattern. Each analyzer defines its own event structure rather than using a shared registry.

This design provides:

• Independent development: Add or modify metrics without coordinating releases across repositories.
• Version tolerance: Older post-analyzers skip unknown events gracefully instead of failing.
• Faster iteration: Test new metrics locally without infrastructure updates.
• Decentralized ownership: Each analyzer team owns their event definitions.

The trade-offs are:

• No single location lists all possible events. Use the monolith event definitions in config/events/ or ee/config/events/ as the source of truth.
• New events aren’t processed until the post-analyzer and backend are updated.

Prerequisites

The observability feature requires:

• Report package v7 or later
• Command package v5 or later

Event design guidance

• Create multiple events rather than using many extra properties. JSON columns with extra properties are slower to query.
• To join related events, include a UUID in a column value (for example, property).
• Before adding a variable field, check with maintainers of the integration-test project to ensure it will be handled correctly.

Register the internal event

Events require a corresponding definition in the GitLab monolith and must be added to the backend allow list. Only allowed events are processed.

1. Create event definition in config/events/ or ee/config/events/.
2. Update the allow list in ProcessScanEventsService.
3. Add an rspec test using actual report output from the analyzer.

For more information, see Quick start for internal event tracking.

Validation

After deployment:

1. Query Snowflake to verify events are collected correctly.
2. Check Sentry for exceptions during report processing.
3. Request dashboard creation from the Analytics Instrumentation team.