Observability Complete Guide

# Observability Complete Guide for Google Antigravity

Build observable applications with structured logging and comprehensive monitoring using Google Antigravity IDE.

## Structured Logging Setup

```typescript
// lib/logger.ts
import pino from "pino";
import { AsyncLocalStorage } from "async_hooks";

// Request context storage
const requestContext = new AsyncLocalStorage<{
  requestId: string;
  userId?: string;
  path?: string;
}>();

const logger = pino({
  level: process.env.LOG_LEVEL || "info",
  formatters: {
    level: (label) => ({ level: label }),
    bindings: () => ({})
  },
  timestamp: pino.stdTimeFunctions.isoTime,
  mixin() {
    const context = requestContext.getStore();
    return context ? { ...context } : {};
  },
  redact: {
    paths: ["password", "token", "authorization", "cookie"],
    censor: "[REDACTED]"
  }
});

export { logger, requestContext };

// Middleware for request context
export function withRequestContext(handler: Function) {
  return async (req: Request, ...args: unknown[]) => {
    const requestId = req.headers.get("x-request-id") || crypto.randomUUID();
    const userId = req.headers.get("x-user-id") || undefined;
    
    return requestContext.run({ requestId, userId, path: new URL(req.url).pathname }, () =>
      handler(req, ...args)
    );
  };
}

// Usage example
export function logError(error: Error, context?: Record<string, unknown>) {
  logger.error({
    err: {
      name: error.name,
      message: error.message,
      stack: error.stack
    },
    ...context
  }, error.message);
}

export function logInfo(message: string, data?: Record<string, unknown>) {
  logger.info(data, message);
}

export function logWarning(message: string, data?: Record<string, unknown>) {
  logger.warn(data, message);
}
```

## OpenTelemetry Integration

```typescript
// lib/tracing.ts
import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: process.env.SERVICE_NAME || "my-app",
    [SemanticResourceAttributes.SERVICE_VERSION]: process.env.APP_VERSION || "1.0.0",
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || "development"
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/traces"
  }),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new OTLPMetricExporter({
      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT + "/v1/metrics"
    }),
    exportIntervalMillis: 30000
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      "@opentelemetry/instrumentation-fs": { enabled: false }
    })
  ]
});

sdk.start();

process.on("SIGTERM", () => {
  sdk.shutdown()
    .then(() => console.log("Tracing terminated"))
    .catch((error) => console.error("Error terminating tracing", error))
    .finally(() => process.exit(0));
});
```

## Custom Metrics

```typescript
// lib/metrics.ts
import { metrics, Counter, Histogram, UpDownCounter } from "@opentelemetry/api";

const meter = metrics.getMeter("my-app");

// HTTP request metrics
export const httpRequestDuration = meter.createHistogram("http_request_duration_ms", {
  description: "HTTP request duration in milliseconds",
  unit: "ms"
});

export const httpRequestTotal = meter.createCounter("http_requests_total", {
  description: "Total number of HTTP requests"
});

export const httpRequestErrors = meter.createCounter("http_request_errors_total", {
  description: "Total number of HTTP request errors"
});

// Business metrics
export const activeUsers = meter.createUpDownCounter("active_users", {
  description: "Number of currently active users"
});

export const ordersProcessed = meter.createCounter("orders_processed_total", {
  description: "Total number of orders processed"
});
```

## Best Practices

1. **Use structured logging** with consistent fields
2. **Include request context** in all logs
3. **Redact sensitive information** automatically
4. **Implement distributed tracing** across services
5. **Create custom business metrics**
6. **Set up alerts** for critical thresholds
7. **Use log aggregation** for centralized analysis

Google Antigravity helps implement observability patterns and suggests monitoring configurations.