Instrumentation

TokenAuthority emits ActiveSupport::Notifications instrumentation events for performance monitoring. These events provide timing data that APM tools (New Relic, Datadog, Skylight) automatically capture.

Configuration

Instrumentation is enabled by default. Configure it in your initializer:

TokenAuthority.configure do |config|
  # Enable/disable instrumentation (default: true)
  config.instrumentation_enabled = true
end

When enabled, TokenAuthority automatically logs instrumentation events to Rails.logger at info level.

Events Reference

All events are namespaced with token_authority. prefix and include timing information.

JWT Operations

Event	Payload	Description
`token_authority.jwt.encode`	`token_size`	JWT token encoding
`token_authority.jwt.decode`	`token_size`	JWT token decoding

Session Operations

Event	Payload	Description
`token_authority.session.create`	(none)	New session created (token issuance)
`token_authority.session.refresh`	(none)	Session refreshed via refresh token
`token_authority.session.revoke`	(none)	Session revoked

Grant Operations

Event	Payload	Description
`token_authority.grant.redeem`	(none)	Authorization grant redeemed for tokens

Client Operations

Event	Payload	Description
`token_authority.client.resolve`	`client_type`	Client ID resolved (`"registered"` or `"url_based"`)
`token_authority.client_metadata.fetch`	`uri`, `cache_hit`	Client metadata document fetched
`token_authority.jwks.fetch`	`uri`, `cache_hit`	JWKS fetched for client authentication

Event Flow Examples

A complete token exchange emits:

token_authority.client.resolve (0.5ms) client_type="registered"
token_authority.grant.redeem (1.2ms)
token_authority.session.create (15ms)
  ├── token_authority.jwt.encode (0.4ms) token_size=312
  └── token_authority.jwt.encode (0.4ms) token_size=198

A token refresh emits:

token_authority.client.resolve (0.5ms) client_type="registered"
token_authority.jwt.decode (0.3ms) token_size=256
token_authority.session.refresh (15ms)
  └── token_authority.session.create (12ms)
        ├── token_authority.jwt.encode (0.4ms) token_size=312
        └── token_authority.jwt.encode (0.4ms) token_size=198

A token revocation emits:

token_authority.client.resolve (0.5ms) client_type="registered"
token_authority.jwt.decode (0.3ms) token_size=256
token_authority.session.revoke (5ms)

Custom Subscribers

You can add your own subscribers for custom metrics collection:

# config/initializers/token_authority_instrumentation.rb
ActiveSupport::Notifications.subscribe(/^token_authority\./) do |name, start, finish, id, payload|
  duration_ms = (finish - start) * 1000

  # Send to your metrics system
  StatsD.timing(name.tr(".", "_"), duration_ms)

  # Add custom tags based on payload
  if payload[:client_type]
    StatsD.increment("token_authority.client_resolution", tags: ["type:#{payload[:client_type]}"])
  end
end

Datadog Example

ActiveSupport::Notifications.subscribe(/^token_authority\./) do |name, start, finish, id, payload|
  Datadog::Statsd.new.distribution(
    name,
    (finish - start) * 1000,
    tags: payload.map { |k, v| "#{k}:#{v}" }
  )
end

Prometheus Example

# Define metrics
TOKEN_AUTHORITY_DURATION = Prometheus::Client::Histogram.new(
  :token_authority_operation_duration_seconds,
  docstring: "TokenAuthority operation duration",
  labels: [:operation],
  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1]
)

ActiveSupport::Notifications.subscribe(/^token_authority\./) do |name, start, finish, id, payload|
  operation = name.sub("token_authority.", "")
  TOKEN_AUTHORITY_DURATION.observe(finish - start, labels: { operation: operation })
end

Disabling Instrumentation

To completely disable instrumentation:

TokenAuthority.configure do |config|
  config.instrumentation_enabled = false
end

When disabled, the instrument calls become no-ops with minimal overhead.