Monitoring

Monitor ACOR performance with built-in observability support.

Overview

ACOR provides three pillars of observability:

Metrics: Prometheus-compatible metrics
Logging: Structured JSON logging
Tracing: OpenTelemetry distributed tracing

graph LR
    A[ACOR] --> B[Metrics]
    A --> C[Logs]
    A --> D[Traces]

    B --> E[Prometheus]
    C --> F[Log Aggregator]
    D --> G[Jaeger/Zipkin]

Metrics

Import the metrics package:

import "github.com/skyoo2003/acor/pkg/metrics"

Available Metrics

Metric	Type	Description
`acor_http_requests_total`	Counter	Total HTTP requests by method, path, status
`acor_http_request_duration_seconds`	Histogram	HTTP request latency
`acor_grpc_requests_total`	Counter	Total gRPC requests by method, status
`acor_grpc_request_duration_seconds`	Histogram	gRPC request latency
`acor_redis_operations_total`	Counter	Total Redis operations by type, status
`acor_redis_operation_duration_seconds`	Histogram	Redis operation latency
`acor_keywords_total`	Gauge	Number of registered keywords
`acor_trie_nodes_total`	Gauge	Number of trie nodes

Exposing Metrics

import (
    "net/http"

    "github.com/prometheus/client_golang/prometheus/promhttp"
    "github.com/skyoo2003/acor/pkg/metrics"
)

func main() {
    // nil registerer defaults to prometheus.DefaultRegisterer,
    // which is what promhttp.Handler() serves
    _ = metrics.NewRegistry(nil)

    http.Handle("/metrics", promhttp.Handler())
    http.ListenAndServe(":8080", nil)
}

Logging

Import the logging package:

import "github.com/skyoo2003/acor/pkg/logging"

Structured Logging

logger := logging.NewLogger(logging.Config{
    Level:  "info",
    Format: "json",
})

logger.Info("operation completed",
    "operation", "Find",
    "duration_ms", 12,
    "matches", 5,
)

Log Levels

debug: Detailed debugging info
info: General operational info
warn: Warning conditions
error: Error conditions

Tracing

Import the tracing package:

import "github.com/skyoo2003/acor/pkg/tracing"

OpenTelemetry Setup

tracer, err := tracing.NewTracer(&tracing.Config{
    Enabled:     true,
    ServiceName: "my-service",
    Endpoint:    "localhost:4317",
    SampleRatio: 1.0,
})
if err != nil {
    // handle error
}
defer tracer.Shutdown()

Spans

ACOR automatically creates spans for:

acor.Add
acor.Find
acor.Remove
Redis operations

Dashboards

Key Metrics to Monitor

Operation Latency: P50, P95, P99
Error Rate: Operations failing
Keyword Count: Collection size
Redis Connections: Pool utilization

Grafana Dashboard

Create a Grafana dashboard using the metrics above. Key panels to include:

Operation Latency: P50/P95/P99 of acor_redis_operation_duration_seconds
Error Rate: Rate of acor_redis_operations_total{status="error"}
Keyword Count: Gauge acor_keywords_total
Trie Nodes: Gauge acor_trie_nodes_total

Alerting Rules

groups:
  - name: acor
    rules:
      - alert: HighLatency
        expr: histogram_quantile(0.95, rate(acor_redis_operation_duration_seconds_bucket[5m])) > 0.1
        for: 5m
        annotations:
          summary: "ACOR operations are slow"

      - alert: HighRedisErrorRate
        expr: rate(acor_redis_operations_total{status="error"}[5m]) > 0.1
        for: 5m
        annotations:
          summary: "High Redis error rate"