Instrumentation Examples

Examples of using span metrics to debug performance issues and monitor application behavior across frontend and backend services.

This guide provides practical examples of using span metrics to solve common monitoring and debugging challenges across your entire application stack. Each example demonstrates how to instrument both frontend and backend components, showing how they work together within a distributed trace to provide end-to-end visibility.

Challenge: Understanding bottlenecks and failures in multi-step file processing operations across client and server components.

Solution: Track the entire file processing pipeline with detailed metrics at each stage, from client-side upload preparation through server-side processing.

Frontend Instrumentation:

Copied
// Client-side file upload handling
Sentry.startSpan(
  {
    name: "Client File Upload",
    op: "file.upload.client",
    attributes: {
      // Client-side file preparation
      "file.size_bytes": 15728640, // 15MB
      "file.type": "image/jpeg",
      "file.name": "user-profile.jpg",

      // Client processing metrics
      "client.chunk_size": 1048576, // 1MB chunks
      "client.chunks_total": 15,
      "client.compression_applied": true,

      // Upload progress tracking
      "upload.chunks_sent": 15,
      "upload.retry_count": 0,
      "upload.total_time_ms": 3500,
    },
  },
  async () => {
    // Client-side upload implementation
  },
);

Backend Instrumentation:

Copied
// Server-side processing
Sentry.startSpan(
  {
    name: "Server File Processing",
    op: "file.process.server",
    attributes: {
      // Server processing steps
      "processing.steps_completed": [
        "virus_scan",
        "resize",
        "compress",
        "metadata",
      ],
      "processing.output_size_bytes": 524288, // 512KB
      "processing.compression_ratio": 0.033,

      // Storage operations
      "storage.provider": "s3",
      "storage.region": "us-west-2",
      "storage.upload_time_ms": 850,

      // CDN configuration
      "cdn.provider": "cloudfront",
      "cdn.propagation_ms": 1500,
    },
  },
  async () => {
    // Server-side processing implementation
  },
);

How the Trace Works Together: The frontend span initiates the trace and handles the file upload process. It propagates the trace context to the backend through the upload request headers. The backend span continues the trace, processing the file and storing it. This creates a complete picture of the file's journey from client to CDN, allowing you to:

  • Identify bottlenecks at any stage (client prep, upload, server processing, CDN propagation)
  • Track end-to-end processing times and success rates
  • Monitor resource usage across the stack
  • Correlate client-side upload issues with server-side processing errors

Challenge: Managing cost (token usage) and performance of LLM integrations across frontend and backend coponents.

Solution: Tracking of the entire LLM interaction flow, from user input to response rendering.

Frontend Instrumentation:

Copied
// Client-side LLM interaction handling
Sentry.startSpan(
  {
    name: "LLM Client Interaction",
    op: "ai.client",
    attributes: {
      // User interaction metrics
      "input.char_count": 280,
      "input.language": "en",
      "input.type": "question",

      // UI performance
      "ui.time_to_first_token_ms": 245,
      "ui.tokens_per_second": 15,
      "ui.total_render_time_ms": 3250,

      // Stream handling
      "stream.buffer_size": 10,
      "stream.chunks_received": 42,
      "stream.rendering_mode": "markdown",
    },
  },
  async () => {
    // Client-side LLM handling
  },
);

Backend Instrumentation:

Copied
// Server-side LLM processing
Sentry.startSpan(
  {
    name: "LLM API Processing",
    op: "ai.server",
    attributes: {
      // Model configuration
      "llm.model": "gpt-4",
      "llm.temperature": 0.7,
      "llm.max_tokens": 2000,

      // Token usage metrics
      "llm.prompt_tokens": 425,
      "llm.completion_tokens": 632,
      "llm.total_tokens": 1057,

      // Performance tracking
      "llm.api_latency_ms": 2800,
      "llm.queue_time_ms": 150,

      // Cost tracking
      "llm.cost_usd": 0.076,
      "llm.rate_limit_remaining": 95,
    },
  },
  async () => {
    // Server-side LLM processing
  },
);

How the Trace Works Together: The frontend span captures the user interaction and UI rendering performance, while the backend span tracks the actual LLM API interaction. The distributed trace shows the complete flow from user input to rendered response, enabling you to:

  • Analyze end-to-end response times and user experience
  • Track costs and token usage patterns
  • Optimize streaming performance and UI rendering
  • Monitor rate limits and queue times
  • Correlate user inputs with model performance

Challenge: Understanding the complete purchase flow and identifying revenue-impacting issues across the entire stack.

Solution: Track the full checkout process from cart interaction to order fulfillment.

Frontend Instrumentation:

Copied
// Client-side checkout process
Sentry.startSpan(
  {
    name: "Checkout UI Flow",
    op: "commerce.checkout.client",
    attributes: {
      // Cart interaction metrics
      "cart.items_added": 3,
      "cart.items_removed": 0,
      "cart.update_count": 2,

      // User interaction tracking
      "ui.form_completion_time_ms": 45000,
      "ui.payment_method_changes": 1,
      "ui.address_validation_retries": 0,

      // Client performance
      "client.page_load_time_ms": 850,
      "client.payment_widget_load_ms": 650,
      "client.total_interaction_time_ms": 120000,
    },
  },
  async () => {
    // Client-side checkout implementation
  },
);

Backend Instrumentation:

Copied
// Server-side order processing
Sentry.startSpan(
  {
    name: "Order Processing",
    op: "commerce.order.server",
    attributes: {
      // Order details
      "order.id": "ord_123456789",
      "order.total_amount": 159.99,
      "order.currency": "USD",
      "order.items": ["SKU123", "SKU456", "SKU789"],

      // Payment processing
      "payment.provider": "stripe",
      "payment.method": "credit_card",
      "payment.processing_time_ms": 1200,

      // Inventory checks
      "inventory.check_time_ms": 150,
      "inventory.all_available": true,

      // Fulfillment
      "fulfillment.warehouse": "WEST-01",
      "fulfillment.shipping_method": "express",
      "fulfillment.estimated_delivery": "2024-03-20",
    },
  },
  async () => {
    // Server-side order processing
  },
);

How the Trace Works Together: The frontend span tracks the user's checkout experience, while the backend span handles order processing and fulfillment. The distributed trace provides visibility into the entire purchase flow, allowing you to:

  • Analyze checkout funnel performance and drop-off points
  • Track payment processing success rates and timing
  • Monitor inventory availability impact on conversions
  • Measure end-to-end order completion times
  • Identify friction points in the user experience

Challenge: Maintaining reliability and performance of critical API integrations across client and server components.

Solution: Detailed tracking of API interactions from both consumer and provider perspectives.

Frontend Instrumentation:

Copied
// Client-side API consumer
Sentry.startSpan(
  {
    name: "API Client Request",
    op: "http.client",
    attributes: {
      // Request context
      "http.endpoint": "/api/users",
      "http.method": "POST",

      // Client metrics
      "client.retry_count": 0,
      "client.cache_status": "miss",
      "client.network_type": "4g",

      // Request lifecycle
      "request.size_bytes": 1024,
      "request.preparation_time_ms": 50,
      "response.parse_time_ms": 75,

      // Error handling
      "error.type": null,
      "error.retry_strategy": "exponential",
    },
  },
  async () => {
    // Client-side API call
  },
);

Backend Instrumentation:

Copied
// Server-side API provider
Sentry.startSpan(
  {
    name: "API Server Handler",
    op: "http.server",
    attributes: {
      // Request processing
      "server.handler": "UserController.create",
      "server.processing_time_ms": 150,

      // Database interaction
      "db.query_count": 3,
      "db.total_query_time_ms": 85,

      // Response metrics
      "response.size_bytes": 2048,
      "response.status_code": 200,

      // Rate limiting
      "rate_limit.remaining": 95,
      "rate_limit.reset_ms": 3600000,
    },
  },
  async () => {
    // Server-side request handling
  },
);

How the Trace Works Together: The frontend span captures the API consumer perspective, while the backend span tracks the server-side processing. The distributed trace provides full visibility into the API interaction, enabling you to:

  • Monitor end-to-end API request lifecycles
  • Track client-side network conditions and their impact
  • Analyze server processing efficiency
  • Identify bottlenecks in database queries
  • Monitor rate limit usage and impact

For more information about implementing these examples effectively, see our Span Metrics guide which includes detailed best practices and implementation guidelines.

Previous
Span Metrics
Next
Building Custom Spans
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").