/observe

allowed-tools: Task, Read, Write, MultiEdit, Bash(fd:*), Bash(rg:*), Bash(jq:*), Bash(gdate:*), Bash(docker:*), Bash(kubectl:*), Bash(git:*)
name: "Observe"
description: "Transform applications into fully observable systems with comprehensive metrics, logging, tracing, and monitoring dashboards"
author: "wcygan"
tags: ["ops","monitor"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N 2>/dev/null || date +%s%N 2>/dev/null || echo "$(date +%s)$(jot -r 1 100000 999999 2>/dev/null || shuf -i 100000-999999 -n 1 2>/dev/null || echo $RANDOM$RANDOM)"`
• Target service: $ARGUMENTS
• Current directory: !`pwd`
• Project languages: !`fd "(Cargo.toml|go.mod|package.json|pom.xml|build.gradle|deno.json)" . -d 3 | head -5 || echo "No build files detected"`
• Existing observability: !`fd "(prometheus|grafana|otel|jaeger|zipkin)" . -t d -d 2 | head -3 || echo "No existing observability detected"`
• Docker environment: !`docker info >/dev/null 2>&1 && echo "✓ Docker available" || echo "✗ Docker not available"`
• Kubernetes context: !`kubectl config current-context 2>/dev/null || echo "No k8s context"`
• Git branch: !`git branch --show-current 2>/dev/null || echo "Not in git repo"`
• Service discovery: !`rg -l "(main|app|server|service)" --type-add 'code:*.{go,rs,java,js,ts,py}' --type code . | head -3 || echo "No main service files found"`

Your Task

STEP 1: Initialize observability transformation session

• CREATE session state file: `/tmp/observability-session-$SESSION_ID.json`
• ANALYZE target service architecture from Context section
• DETERMINE technology stack and existing observability infrastructure
• VALIDATE required tools and environments (Docker, Kubernetes, build tools)

# Initialize observability session state
echo '{
  "sessionId": "'$SESSION_ID'",
  "targetService": "'$ARGUMENTS'",
  "detectedLanguages": [],
  "existingObservability": [],
  "transformationStrategy": "full-stack",
  "generatedArtifacts": []
}' > /tmp/observability-session-$SESSION_ID.json

STEP 2: Service architecture analysis with parallel discovery

IF complex_service_architecture OR multiple_technologies_detected:

LAUNCH parallel sub-agents for comprehensive service analysis:

• **Agent 1: Service Discovery**: Analyze service structure, entry points, and main components
• Focus: Main service files, configuration, deployment manifests
• Extract: Service architecture, technology stack, existing instrumentation
• Output: Service profile with observability requirements

• **Agent 2: Dependencies Analysis**: Map external dependencies and integration points
• Focus: Database connections, external APIs, message queues, caches
• Extract: Integration patterns, failure points, latency sources
• Output: Dependency map with observability insertion points

• **Agent 3: Existing Observability Audit**: Assess current monitoring and logging
• Focus: Existing metrics, logging frameworks, monitoring tools
• Extract: Current observability gaps and enhancement opportunities
• Output: Observability gap analysis and enhancement plan

• **Agent 4: Technology Stack Assessment**: Evaluate framework-specific observability options
• Focus: Language-specific libraries, framework integrations, best practices
• Extract: Optimal instrumentation libraries and patterns
• Output: Technology-specific implementation recommendations

ELSE:

**Direct Service Analysis:**

• EXECUTE targeted service discovery using project language detection
• IDENTIFY main service entry points and key business logic
• ANALYZE existing observability patterns and gaps

STEP 3: Comprehensive observability instrumentation

TRY:

**Metrics Instrumentation Implementation:**

CASE detected_language: WHEN "go":

• IMPLEMENT Prometheus metrics with histogram and counter patterns
• ADD HTTP middleware for request duration, rate, and error tracking
• CREATE custom business metrics for service-specific operations
• GENERATE `/metrics` endpoint with proper Prometheus exposition format

// Generated metrics instrumentation
var (
    httpDuration = prometheus.NewHistogramVec(
        prometheus.HistogramOpts{
            Name: "http_request_duration_seconds",
            Help: "Duration of HTTP requests",
            Buckets: prometheus.DefBuckets,
        },
        []string{"method", "endpoint", "status_code"},
    )
    
    requestsTotal = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total", 
            Help: "Total number of HTTP requests",
        },
        []string{"method", "endpoint", "status_code"},
    )
)

WHEN "rust":

• IMPLEMENT metrics crate with Prometheus exporter
• ADD axum/warp middleware for automatic HTTP instrumentation
• CREATE custom gauges and histograms for application metrics
• INTEGRATE with tracing ecosystem for structured observability

// Generated Rust metrics
use metrics::{counter, histogram, gauge};

#[instrument]
async fn handle_request(req: Request<Body>) -> Result<Response<Body>, Error> {
    let start = Instant::now();
    let method = req.method().as_str();
    let path = req.uri().path();
    
    let result = process_request(req).await;
    
    let duration = start.elapsed().as_secs_f64();
    histogram!("http_request_duration_seconds")
        .with_tag("method", method)
        .with_tag("path", path)
        .record(duration);
        
    counter!("http_requests_total")
        .with_tag("method", method)
        .with_tag("status", result.status().as_str())
        .increment(1);
        
    result
}

WHEN "java":

• IMPLEMENT Micrometer metrics with Spring Boot Actuator
• ADD automatic HTTP request instrumentation
• CREATE custom meters for business logic monitoring
• CONFIGURE Prometheus registry for metric exposition

WHEN "javascript|typescript":

• IMPLEMENT prom-client for Node.js applications
• ADD Express/Fastify middleware for HTTP metrics