Telemetry integration for DocuSign API operations.

This module provides telemetry events for monitoring and observability of DocuSign API interactions. It builds on top of the underlying Finch telemetry events to provide DocuSign-specific metrics.

Events

The following telemetry events are emitted:

API Operation Events

• [:docusign, :api, :start] - Executed before making an API call

  Measurements:

  • :system_time - System time when the operation started

  Metadata:

  • :operation - The API operation being performed (e.g., "envelopes_post_envelopes")
  • :account_id - The DocuSign account ID
  • :method - HTTP method (:get, :post, etc.)
  • :path - API path being called
  • :connection - The DocuSign.Connection struct

• [:docusign, :api, :stop] - Executed after a successful API call

  Measurements:

  • :duration - Time taken for the operation in native units

  Metadata:

  • :operation - The API operation performed
  • :account_id - The DocuSign account ID
  • :method - HTTP method
  • :path - API path
  • :status - HTTP response status code
  • :connection - The DocuSign.Connection struct

• [:docusign, :api, :exception] - Executed when an API call fails

  Measurements:

  • :duration - Time taken before failure in native units

  Metadata:

  • :operation - The API operation attempted
  • :account_id - The DocuSign account ID (if available)
  • :method - HTTP method
  • :path - API path
  • :kind - The kind of exception (:throw, :error, :exit)
  • :reason - The exception reason/error
  • :stacktrace - The stacktrace
  • :connection - The DocuSign.Connection struct

Authentication Events

• [:docusign, :auth, :token_refresh] - Executed when refreshing an OAuth tokenMeasurements:
  • :duration - Time taken to refresh the token
  Metadata:
  • :success - Boolean indicating if refresh succeeded
  • :user_id - User ID for JWT auth (if applicable)

Rate Limiting Events

• [:docusign, :rate_limit, :hit] - Executed when hitting a rate limitMeasurements:
  • :retry_after - Seconds to wait before retry (from header)
  Metadata:
  • :operation - The API operation that hit the limit
  • :account_id - The DocuSign account ID

Usage Examples

Basic Handler

defmodule MyApp.DocuSignTelemetry do
  require Logger

  def attach do
    :telemetry.attach_many(
      "docusign-handler",
      [
        [:docusign, :api, :start],
        [:docusign, :api, :stop],
        [:docusign, :api, :exception]
      ],
      &handle_event/4,
      nil
    )
  end

  def handle_event([:docusign, :api, :stop], measurements, metadata, _config) do
    Logger.info(
      "DocuSign API call completed",
      operation: metadata.operation,
      duration_ms: System.convert_time_unit(measurements.duration, :native, :millisecond),
      status: metadata.status
    )
  end

  def handle_event([:docusign, :api, :exception], _measurements, metadata, _config) do
    Logger.error(
      "DocuSign API call failed",
      operation: metadata.operation,
      error: metadata.reason
    )
  end

  def handle_event(_event, _measurements, _metadata, _config), do: :ok
end

Integration with Telemetry.Metrics

defmodule MyApp.Telemetry do
  import Telemetry.Metrics

  def metrics do
    [
      # API performance metrics
      summary("docusign.api.duration",
        unit: {:native, :millisecond},
        tags: [:operation, :status]
      ),

      # Request rate
      counter("docusign.api.count",
        tags: [:operation, :status]
      ),

      # Error rate
      counter("docusign.api.exception.count",
        tags: [:operation]
      ),

      # Rate limiting
      counter("docusign.rate_limit.hit.count",
        tags: [:operation]
      )
    ]
  end
end

Finch Telemetry Events

Since DocuSign uses Req/Finch under the hood, you also have access to lower-level HTTP telemetry:

• [:finch, :request, :start] - HTTP request started
• [:finch, :request, :stop] - HTTP request completed
• [:finch, :queue, :start] - Request queued for connection pool
• [:finch, :queue, :stop] - Request dequeued
• [:finch, :connect, :start] - Connection establishment started
• [:finch, :connect, :stop] - Connection established

See Finch.Telemetry for complete documentation of these events.