navan-observability

Navan Observability

Overview

Navan exposes no built-in API metrics dashboard — monitoring is your responsibility. This skill implements structured logging, latency tracking, error classification, and alerting for Navan REST API integrations. Since Navan uses OAuth 2.0 with token expiration, observability must also cover the authentication lifecycle. Patterns are provided for Datadog, CloudWatch, and Prometheus/Grafana.

Prerequisites

• Running Navan API integration with OAuth 2.0 credentials
• Monitoring platform — Datadog, AWS CloudWatch, or Prometheus/Grafana
• Node.js 18+ or equivalent runtime for the instrumentation middleware
• API base URL: https://api.navan.com/v1

Instructions

Step 1 — Instrument API Calls with Structured Logging

Wrap every Navan API call with timing, status, and correlation tracking:

import { randomUUID } from 'crypto';

interface NavanApiLog {
  event: 'navan.api.request';
  correlation_id: string;
  method: string;
  endpoint: string;
  status: number;
  duration_ms: number;
  error_type?: 'auth' | 'rate_limit' | 'server' | 'client' | 'network';
  timestamp: string;
}

async function navanRequest(
  method: string,
  endpoint: string,
  token: string,
  body?: object
): Promise<Response> {
  const correlationId = randomUUID();
  const start = performance.now();

  try {
    const response = await fetch(`https://api.navan.com/v1/${endpoint}`, {
      method,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
        'X-Correlation-ID': correlationId,
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    const log: NavanApiLog = {
      event: 'navan.api.request',
      correlation_id: correlationId,
      method,
      endpoint,
      status: response.status,
      duration_ms: Math.round(performance.now() - start),
      timestamp: new Date().toISOString(),
    };

    if (response.status === 401) log.error_type = 'auth';
    else if (response.status === 429) log.error_type = 'rate_limit';
    else if (response.status >= 500) log.error_type = 'server';
    else if (response.status >= 400) log.error_type = 'client';

    console.log(JSON.stringify(log));
    return response;
  } catch (err) {
    console.log(JSON.stringify({
      event: 'navan.api.request',
      correlation_id: correlationId,
      method,
      endpoint,
      status: 0,
      duration_ms: Math.round(performance.now() - start),
      error_type: 'network',
      error_message: (err as Error).message,
      timestamp: new Date().toISOString(),
    }));
    throw err;
  }
}

Step 2 — Track OAuth Token Lifecycle

async function refreshToken(clientId: string, clientSecret: string): Promise<string> {
  const start = performance.now();
  const response = await fetch('https://api.navan.com/ta-auth/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: clientId,
      client_secret: clientSecret,
    }),
  });

  console.log(JSON.stringify({
    event: 'navan.auth.refresh',
    status: response.status,
    duration_ms: Math.round(performance.now() - start),
    success: response.status === 200,
    timestamp: new Date().toISOString(),
  }));

  if (!response.ok) throw new Error(`Auth failed: HTTP ${response.status}`);
  const data = await response.json();
  return data.access_token;
}

Step 3 — Define Alert Rules

Datadog monitor configuration:

# datadog-monitors/navan-alerts.yaml
monitors:
  - name: "Navan API Auth Failures"
    type: metric alert
    query: >
      sum(last_5m):sum:navan.api.errors{error_type:auth}.as_count() > 3
    message: |
      Navan OAuth token may be expired or credentials rotated.
      Check: Admin > API Settings for credential status.
      Runbook: https://wiki.internal/navan-auth-rotation
    priority: P2

  - name: "Navan API Rate Limiting"
    type: metric alert
    query: >
      sum(last_15m):sum:navan.api.errors{error_type:rate_limit}.as_count() > 10
    message: |
      Navan API returning 429 rate limit responses.
      Action: Reduce sync frequency or implement backoff.
    priority: P3

  - name: "Navan API Latency Degradation"
    type: metric alert
    query: >
      avg(last_10m):p95:navan.api.duration_ms{*} > 5000
    message: |
      Navan API p95 latency exceeds 5 seconds.
      Impact: Expense sync and booking operations are slow.
    priority: P3

  - name: "Navan API Server Errors"
    type: metric alert
    query: >
      sum(last_5m):sum:navan.api.errors{error_type:server}.as_count() > 5
    message: |
      Navan API returning 5xx server errors.
      This is likely a Navan-side issue — check status page.
    priority: P2

Step 4 — Build the Dashboard

Key metrics to display:

Metric	Source	Panel Type
Request rate (rpm)	navan.api.request count	Time series
Latency p50/p95/p99	navan.api.duration_ms	Percentile graph
Error rate by type	navan.api.errors by error_type	Stacked bar
Token refresh success rate	navan.auth.refresh	Single stat
Active correlation IDs	navan.api.request unique correlation_id	Count

Prometheus queries:

# Request rate per minute
rate(navan_api_requests_total[5m]) * 60

# p95 latency
histogram_quantile(0.95, rate(navan_api_duration_seconds_bucket[5m]))

# Error rate percentage
sum(rate(navan_api_errors_total[5m])) / sum(rate(navan_api_requests_total[5m])) * 100

# Auth failure spike detection
increase(navan_api_errors_total{error_type="auth"}[5m]) > 0

Output

A fully instrumented Navan API integration with:

• Structured JSON logs with correlation IDs for request tracing
• Real-time dashboards showing latency, throughput, and error rates
• Automated alerts differentiating auth failures, rate limits, and server errors
• Token lifecycle visibility tracking refresh success and timing

Error Handling

HTTP Code	Error Type	Alert Severity	Action
401	auth	P2 — page on-call	Rotate OAuth credentials immediately
403	client	P3 — notify	Verify API scopes in Navan Admin
429	rate_limit	P3 — notify	Reduce call frequency, check navan-rate-limits skill
500	server	P2 — page if sustained	Check Navan status; nothing to fix on your side
502/503	server	P3 — notify	Transient; retry with backoff
0 (network)	network	P1 — page	DNS, firewall, or connectivity issue

Examples

CloudWatch metric push from a Lambda integration:

# Push custom metric after each Navan API call
aws cloudwatch put-metric-data \
  --namespace "Navan/API" \
  --metric-name "RequestLatency" \
  --value 342 \
  --unit Milliseconds \
  --dimensions Endpoint=bookings,Status=200

Resources

• Navan Help Center — API documentation
• Datadog Custom Metrics — Sending custom metrics
• Prometheus Client Libraries — Instrumentation SDKs
• AWS CloudWatch Custom Metrics

Next Steps

• Add navan-incident-runbook for structured incident response procedures
• Add navan-rate-limits to understand Navan's specific throttling behavior
• See navan-performance-tuning to optimize the API calls being monitored