CID Tracker

Extract correlation IDs from your logs. Automatically.

What is it? • Features • Quick Start • How it Works • Contributing

What is CID Tracker?

"Our microservices generate thousands of log lines per minute. When something breaks, I spend more time correlating logs across services than actually fixing the problem."

Sound familiar? CID Tracker solves this by automatically extracting correlation IDs (CIDs) from your application logs and outputting them as structured data — ready for your observability pipeline.

Deploy it as a sidecar container. It watches your log files, extracts UUIDs used as correlation IDs, validates them, and streams structured output to stdout. No code changes required in your application.

Before CID Tracker

# Scattered across multiple log files, multiple services...
2024-01-15 10:30:00 INFO [auth] CID:550e8400-e29b-51d4-a716-446655440000 User login
2024-01-15 10:30:01 INFO [orders] CID:550e8400-e29b-51d4-a716-446655440000 Fetching cart
2024-01-15 10:30:02 ERROR [payments] CID:550e8400-e29b-51d4-a716-446655440000 Payment failed
# Good luck finding these manually...

After CID Tracker

{"cid":"550e8400-e29b-51d4-a716-446655440000","log_file":"auth.log","timestamp":"2024-01-15T10:30:00Z",...}
{"cid":"550e8400-e29b-51d4-a716-446655440000","log_file":"orders.log","timestamp":"2024-01-15T10:30:01Z",...}
{"cid":"550e8400-e29b-51d4-a716-446655440000","log_file":"payments.log","timestamp":"2024-01-15T10:30:02Z",...}

Pipe this to Elasticsearch, Loki, or any log aggregator — now you can filter by CID instantly.

Features

Core Real-time monitoring — Uses filesystem events, not polling Pattern matching — Configurable regex for your log format UUID validation — Validates extracted IDs, supports v5 enforcement Multiple outputs — JSON or structured text	Operations Sidecar-ready — Minimal footprint, container-native Graceful shutdown — Clean handling of SIGTERM Prometheus metrics — Built-in `/metrics` endpoint Zero dependencies — Single binary, no runtime requirements

Quick Start

See It In Action (30 seconds)

git clone https://github.com/psenger/cidtracker.git
cd cidtracker/examples
docker compose up --build

Watch the output:

sample-app     | 2024-01-15 10:30:00 INFO [auth-service] CID:550e8400-e29b-51d4-a716-446655440000 Processing user request
cidtracker     | {"cid":"550e8400-e29b-51d4-a716-446655440000","uuid":"550e8400-e29b-51d4-a716-446655440000","timestamp":"2024-01-15T10:30:00Z","log_file":"application.log",...}

The sample app generates logs with CIDs. CID Tracker extracts them in real-time.

Press Ctrl+C to stop, then docker compose down -v to clean up.

Install

From Source:

go install github.com/psenger/cidtracker@latest

Build Locally:

git clone https://github.com/psenger/cidtracker.git
cd cidtracker
go build -o cidtracker .

Docker:

docker build -t cidtracker:latest .

Basic Usage

# Monitor a directory, output JSON
./cidtracker -log-path=/var/log/app -output=json

# With verbose logging
./cidtracker -log-path=/var/log/app -output=json -verbose

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Your Application                         │
│                                                                 │
│   logger.info("CID:{} Processing order", correlationId)         │
│                              │                                  │
│                              ▼                                  │
│                    /var/log/app/app.log                         │
└─────────────────────────────────────────────────────────────────┘
                               │
                               │ (shared volume)
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                         CID Tracker                             │
│                                                                 │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│   │  LogMonitor  │───▶│  Extractor   │───▶│  Validator   │      │
│   │  (fsnotify)  │    │  (regex)     │    │  (UUID v5)   │      │
│   └──────────────┘    └──────────────┘    └──────────────┘      │
│                                                  │              │
│                                                  ▼              │
│                                           ┌──────────────┐      │
│                                           │    stdout    │      │
│                                           │    (JSON)    │      │
│                                           └──────────────┘      │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
                    Log Aggregator / SIEM
                (Elasticsearch, Loki, Splunk, etc.)

LogMonitor watches for new .log files and tails existing ones
Extractor applies regex patterns to find CID:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Validator confirms it's a valid UUID (optionally version 5 only)
Output streams structured JSON to stdout for your pipeline

Use Cases

"I'm a platform engineer building a Kubernetes logging stack. I need to enrich logs with correlation metadata before they hit Elasticsearch."

Deploy CID Tracker as a sidecar. Mount the log volume read-only. Pipe stdout to Fluentd/Fluent Bit.

"I'm a developer debugging a distributed system. I need to trace a request across 5 microservices."

Add CID Tracker to your docker-compose. Filter aggregated logs by the extracted CID.

"I'm an SRE setting up alerting. I need to detect when the same correlation ID appears in error logs across multiple services."

Feed CID Tracker output to your SIEM. Create correlation rules based on CID frequency in error streams.

Deployment

Docker Compose (Sidecar)

version: '3.8'
services:
  your-app:
    image: your-app:latest
    volumes:
      - logs:/var/log/app

  cidtracker:
    image: cidtracker:latest
    volumes:
      - logs:/var/log/app:ro
    command: ["-log-path=/var/log/app", "-output=json"]

volumes:
  logs:

Kubernetes

spec:
  containers:
  - name: app
    image: your-app:latest
    volumeMounts:
    - name: logs
      mountPath: /var/log/app

  - name: cidtracker
    image: cidtracker:latest
    args: ["-log-path=/var/log/app", "-output=json"]
    volumeMounts:
    - name: logs
      mountPath: /var/log/app
      readOnly: true
    resources:
      limits:
        memory: "64Mi"
        cpu: "50m"

  volumes:
  - name: logs
    emptyDir: {}

See Deployment Guide for complete examples.

Configuration

Flag	Environment Variable	Default	Description
`-log-path`	`CIDTRACKER_LOG_DIR`	`/var/log/app`	Directory to monitor
`-output`	`CIDTRACKER_OUTPUT_FORMAT`	`json`	Output format (`json` / `structured`)
`-verbose`	`CIDTRACKER_LOG_LEVEL=debug`	`false`	Enable debug logging

Project Status

Alpha — Core functionality works. Not yet recommended for production.

What Works

In Progress

HTTP server with /health and /metrics
Configurable CID patterns via file
Log rotation handling

Planned

Multi-file correlation
Custom output destinations
UUID version 7 support

Documentation

Document	Description
API Reference	HTTP endpoints (when enabled)
Deployment Guide	Docker, Kubernetes, and configuration
Examples	Working docker-compose demo
Contributing	How to contribute

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

The short version:

Open an issue first — Let's discuss before you code
Fork → Branch → Code → Test
Ensure 75% test coverage minimum
Submit PR referencing the issue

# Run tests
go test ./...

# Check coverage
go test -cover ./...

License

MIT License — see LICENSE for details.

Acknowledgments

Built with:

fsnotify — File system notifications
google/uuid — UUID parsing
logrus — Structured logging

_{Built with Go. Made for observability.}

psenger/cidtracker