Observe

Monitor, analyze, and optimize your business operations in real-time.

Overview

The Observe phase provides complete visibility into your Business-as-Code and Services-as-Software in production. Through monitoring, logging, analytics, and alerting, you'll understand system health, user behavior, and business performance.

Observability on the .do platform includes:

Built-in Monitoring: Automatic metrics collection for all services
Semantic Logging: Structured logs with business context
Real-time Analytics: Track business events and user behavior
Smart Alerting: Context-aware alerts with suggested fixes
Distributed Tracing: Follow requests across services

The Three Pillars

1. Metrics

Quantitative measurements over time:

Request rates
Response times
Error rates
Resource usage
Business KPIs

Learn more about metrics →

2. Logs

Detailed event records:

Application logs
Error logs
Audit logs
Business event logs

Learn more about logging →

3. Traces

Request flow visualization:

Service dependencies
Performance bottlenecks
Error propagation
Latency breakdown

Learn more about tracing →

Quick Start

Enable Monitoring

Monitoring is enabled by default for all deployments:

// Metrics automatically collected
export default {
  async fetch(request, env) {
    // Request count, latency, errors tracked automatically
    return new Response('Hello')
  },
}

Add Custom Metrics

Track business-specific metrics:

import { metrics } from 'sdk.do'

// Increment counter
await metrics.increment('orders.created', {
  tags: { plan: 'pro', region: 'us-east' },
})

// Record value
await metrics.gauge('revenue.mrr', 99999, {
  tags: { currency: 'USD' },
})

// Track timing
await metrics.timing('api.latency', durationMs, {
  tags: { endpoint: '/api/users' },
})

View Dashboards

Access real-time dashboards:

# Open dashboard
do dashboard

# View specific service
do dashboard api

# View logs
do logs --tail --service api

# View traces
do traces --service api --duration 1h

Observability Patterns

Health Checks

Define health endpoints:

app.get('/health', async (c) => {
  const checks = await Promise.all([checkDatabase(), checkRedis(), checkExternalAPI()])

  const healthy = checks.every((c) => c.ok)

  return c.json(
    {
      status: healthy ? 'healthy' : 'degraded',
      checks: checks.map((c) => ({
        name: c.name,
        status: c.ok ? 'ok' : 'error',
        latency: c.latency,
      })),
    },
    healthy ? 200 : 503
  )
})

Structured Logging

Use semantic logging:

import { log } from 'sdk.do'

// Structured log entry
log.info('Order created', {
  orderId: 'order-123',
  customerId: 'user-456',
  amount: 99.99,
  items: 3,
})

// Error logging with context
log.error('Payment failed', {
  orderId: 'order-123',
  error: error.message,
  stack: error.stack,
  paymentMethod: 'card',
})

Request Tracing

Trace requests across services:

import { trace } from 'sdk.do'

const span = trace.startSpan('process-order')

try {
  // Child spans for sub-operations
  await trace.span('validate-order', async () => {
    await validateOrder(order)
  })

  await trace.span('process-payment', async () => {
    await processPayment(order)
  })

  await trace.span('create-shipment', async () => {
    await createShipment(order)
  })

  span.setStatus('ok')
} catch (error) {
  span.setStatus('error', error.message)
  throw error
} finally {
  span.end()
}

Business Metrics

Track business KPIs:

// Track sign ups
on($.User.registered, async (user) => {
  await metrics.increment('signups.total', {
    tags: { plan: user.plan, source: user.source },
  })
})

// Track revenue
on($.Invoice.paid, async (invoice) => {
  await metrics.gauge('revenue.mrr', invoice.amount, {
    tags: { currency: 'USD', plan: invoice.plan },
  })
})

// Track churn
on($.Subscription.cancelled, async (subscription) => {
  await metrics.increment('churn.total', {
    tags: { plan: subscription.plan, reason: subscription.reason },
  })
})

Alerting

Define Alerts

Set up intelligent alerts:

// Alert on error rate spike
await $.alert.create({
  name: 'High Error Rate',
  condition: 'error_rate > 5% for 5 minutes',
  severity: 'critical',
  channels: ['slack', 'pagerduty'],
})

// Alert on latency
await $.alert.create({
  name: 'Slow API Response',
  condition: 'p95_latency > 1000ms for 10 minutes',
  severity: 'warning',
  channels: ['slack'],
})

// Alert on business metrics
await $.alert.create({
  name: 'Revenue Drop',
  condition: 'revenue.mrr < baseline * 0.9',
  severity: 'high',
  channels: ['slack', 'email'],
})

Alert Channels

Configure notification channels:

Slack: Team notifications
PagerDuty: On-call escalation
Email: Alert summaries
Webhook: Custom integrations

Analytics

User Analytics

Track user behavior:

import { analytics } from 'sdk.do'

// Track page view
await analytics.track('Page Viewed', {
  userId: user.id,
  page: '/products',
  referrer: document.referrer,
})

// Track action
await analytics.track('Product Added to Cart', {
  userId: user.id,
  productId: 'prod-123',
  price: 99.99,
})

// Track conversion
await analytics.track('Purchase Completed', {
  userId: user.id,
  orderId: 'order-123',
  revenue: 99.99,
})

Funnel Analysis

Track conversion funnels:

// Define funnel
const checkoutFunnel = ['Cart Viewed', 'Checkout Started', 'Payment Info Added', 'Order Confirmed']

// Analyze conversion
const funnelData = await analytics.funnel(checkoutFunnel, {
  timeRange: 'last_7_days',
})
// Returns: [100%, 75%, 50%, 40%]

Dashboards

Pre-built Dashboards

Service Health: Availability, latency, errors
Business Metrics: Revenue, users, conversions
Infrastructure: CPU, memory, requests
User Analytics: Traffic, engagement, retention

Custom Dashboards

Create custom views:

// Define custom dashboard
await $.dashboard.create({
  name: 'E-commerce Overview',
  widgets: [
    { type: 'metric', metric: 'orders.total', period: '24h' },
    { type: 'metric', metric: 'revenue.total', period: '24h' },
    { type: 'chart', metric: 'orders.rate', period: '7d' },
    { type: 'funnel', funnel: 'checkout', period: '7d' },
  ],
})

Performance Monitoring

Real User Monitoring (RUM)

Track real user experience:

// Automatically capture
- Page load times
- First contentful paint
- Largest contentful paint
- Cumulative layout shift
- First input delay

Synthetic Monitoring

Proactive uptime checks:

# Create uptime check
do monitor create https://api.example.com/health \
  --interval 1m \
  --regions global \
  --alert-on-failure

Error Tracking

Error Capture

Automatically capture errors:

// Errors automatically captured with context
try {
  await processPayment(order)
} catch (error) {
  // Automatically logged with stack trace, context, and tags
  throw error
}

Error Grouping

Errors grouped by:

Error type
Message pattern
Stack trace similarity
Affected users

Best Practices

Do's

Monitor what matters - Focus on user-impacting metrics
Set actionable alerts - Every alert should require action
Log with context - Include relevant business data
Track business metrics - Not just technical metrics
Use dashboards - Visualize trends and patterns
Review regularly - Weekly metric reviews

Don'ts

Don't over-alert - Too many alerts lead to alert fatigue
Don't log sensitive data - Protect user privacy
Don't ignore trends - Small trends become big problems
Don't skip tracing - Traces help debug complex issues
Don't forget costs - Monitor monitoring costs

Next Steps

Metrics → - Deep dive into metrics
Logging → - Master structured logging
Analytics → - Track business metrics
Alerting → - Set up smart alerts
Debugging → - Debug production issues

Observability Tip: Great observability means understanding not just what's happening, but why it's happening and what to do about it.

Observe

On this page