logbrew-sdk 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233087ef98eb35d7df84720956a89dfbf66368ac55269900a38491192c7a67a3
-  data.tar.gz: 1720b83bf8dcc562771936091f0196996415005e6a5ea254ca4e0a803e3ea1ac
+  metadata.gz: d461f01e0341b81cbdd17c4903f50726cd7966f26e50d7fd6fbef97a8fbf83dc
+  data.tar.gz: 42efb0bf7c1312d5c0bb3337885b00de0921e043952e8c57d6571391110e2c7d
 SHA512:
-  metadata.gz: 1e67486d07bb9334f6cf553111e8e198f1b448105cc491cad566d03e4356a190b00891c054552f9022c9dc982019bce506dc7ab09f7340d3321785935b34fef7
-  data.tar.gz: 66c92e704c995f6a0ab73586eefa8a65cf7aef4af621a3dbbc68c925b6063851ebc422c8d23d5f30de40ea7b111989bd0154ed740fc334d109ce72cfabe8971b
+  metadata.gz: d7f55a9b0a8f8813762a2f497382a78c6678d22972ffe8bd0512359c53a8927491ea4fd7fc5bc92b40aaefab156cd8a57e27a090eedbd012c4b786360d1c6514
+  data.tar.gz: bc21387db2691a355300645a333d4f57f878815415e6b52d1d56d7f38a5bca6be4eb27a4e205ba65ce777d9d05b04e018feeacb752a0ba5df7db5f1ecc83fab4

data/README.md

@@ -23,7 +23,7 @@ needed:
 
 ```ruby
 # Gemfile
-gem "logbrew-sdk", "~> 0.1.3"
+gem "logbrew-sdk", "~> 0.1.4"
 ```
 
 ```bash
@@ -40,11 +40,14 @@ disabled and the application behaves normally. Set `LOGBREW_ENABLED=false` to
 disable it explicitly. If the Gemfile uses `require: false`, load
 `logbrew/rails` yourself after Rails.
 
-The automatic integration records route-template request spans and type-only
-issues. It does not record concrete request paths, query strings, request or
-response bodies, arbitrary headers, authorization values, cookies, user IDs,
-exception messages, or exception backtraces. Exception messages and backtraces
-are separate opt-ins:
+The automatic integration records route-template request spans and typed
+exception issues. Escaped request failures include exception identity,
+`rails.middleware` with `handled: false`, and up to 32 newest-first sanitized
+frames. Handled Rails reports use `rails.error_reporter` with `handled: true`.
+It does not record concrete request paths, query strings, request or response
+bodies, arbitrary headers, authorization values, cookies, user IDs, exception
+messages, raw backtrace text, source snippets, locals, arguments, or absolute
+paths. Exception messages and raw backtrace text are separate opt-ins:
 
 | Environment variable | Default | Purpose |
 | --- | --- | --- |
@@ -58,7 +61,7 @@ are separate opt-ins:
 | `LOGBREW_FLUSH_INTERVAL_MS` | `5000` | Automatic delivery interval from 10 to 3600000 ms |
 | `LOGBREW_FLUSH_THRESHOLD` | `100` | Queue size from 1 to 1000 that requests an earlier flush |
 | `LOGBREW_CAPTURE_EXCEPTION_MESSAGES` | `false` | Opt in to exception message capture |
-| `LOGBREW_INCLUDE_EXCEPTION_BACKTRACE` | `false` | Opt in to exception backtrace capture |
+| `LOGBREW_INCLUDE_EXCEPTION_BACKTRACE` | `false` | Opt in to raw exception backtrace text; sanitized structured frames are always captured |
 
 `LOGBREW_API_KEY` and `LOGBREW_INGEST_KEY` are not Rails aliases. If either is
 set without the canonical server key, startup reports the exact
@@ -137,6 +140,76 @@ response = client.shutdown(LogBrew::RecordingTransport.always_accept)
 warn response.status_code
 ```
 
+## Shared Telemetry Context
+
+Use one versioned context when a human or coding agent must correlate releases,
+issues, logs, spans, metrics, and product actions without reverse-engineering a
+flat metadata map:
+
+```ruby
+resource = LogBrew::TelemetryResource.create
+  .with_service(name: "checkout-api", version: "1.4.0")
+  .with_deployment(environment: "production", release: "checkout@1.4.0")
+  .with_framework(name: "rails", version: "8.1.3")
+  .with_application(name: "checkout", version: "1.4.0", build: "140")
+  .build
+client_context = LogBrew::TelemetryContext.create
+  .with_resource(resource)
+  .with_tag("region", "eu")
+  .build
+
+client = LogBrew::Client.create(
+  api_key: ENV.fetch("LOGBREW_SERVER_API_KEY"),
+  sdk_name: "checkout-api",
+  sdk_version: "1.4.0",
+  context: client_context
+)
+
+request_context = LogBrew::TelemetryContext.create
+  .with_session(id: "session_checkout_123")
+  .with_subject(id: "subject_checkout_123", kind: "user")
+  .with_tags("journey" => "checkout", "surface" => "payment")
+  .build
+
+LogBrew::Telemetry.with_context(request_context) do
+  client.log(
+    "evt_checkout_started",
+    Time.now.utc.iso8601,
+    message: "checkout started",
+    level: "info"
+  )
+end
+```
+
+Client context is merged into all seven signal types. Resource sections and
+tags merge field by field; event context replaces trace, session, or subject
+sections and wins on conflicting resource fields or tags. Pass a built
+`TelemetryContext` as an event's `context:` value for an explicit override.
+`LogBrew::Telemetry.with_context` provides a fiber/thread-local request or job
+scope and returns to the exact prior scope even when application work raises.
+When `LogBrew::Trace.current` is active, its W3C trace and span IDs are added to
+the typed context on every signal. Explicit event context remains the final
+override.
+
+The client adds only Ruby engine/version, operating-system family/release, and
+architecture beneath explicit context by default. Set
+`capture_runtime_context: false` to disable those defaults without removing
+explicit context. The automatic Rails adapter also promotes its already
+validated service, environment, release, and Rails version configuration into
+the corresponding resource sections. Automatic context never reads host names,
+process IDs, commands or arguments, environment variables, local account names,
+working directories, files, network addresses, cloud metadata, memory, or CPU
+values.
+
+Context is detached and validated before queue admission. Strings, IDs, trace
+identifiers, resource sections, and tags follow the shared event schema; tags
+are sorted and capped at 32. Session and subject IDs are application-owned,
+opaque correlation values. Never put names, email addresses, authentication
+material, network addresses, or other direct personal data in them. Use
+`TelemetryContext.from_hash(...)` or `TelemetryResource.from_hash(...)` only
+when adapting an already schema-shaped object; the builders are clearer for
+new code.
+
 ## Serialized Worker Lifecycle
 
 Use `LogBrew::WorkerLifecycle` when a prefork or long-running worker processes
@@ -189,7 +262,9 @@ when that lifecycle fits the application better.
 
 ## First Useful Service Telemetry
 
-For a service request, combine release, environment, log, product action, network milestone, metric, and span events around one shared W3C trace:
+For a service request, combine release, environment, log, product action,
+network milestone, metric, and span events around one typed request context and
+one shared W3C trace:
 
 ```ruby
 incoming = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
@@ -197,51 +272,66 @@ trace = LogBrew::Traceparent.parse(incoming)
 child_span_id = "b7ad6b7169203331"
 route_template = "/checkout/:cart_id"
 session_id = "sess_checkout_123"
-
-client.log(
-  "evt_log_checkout_started",
-  "2026-06-02T10:00:02Z",
-  message: "checkout request started",
-  level: "info",
-  logger: "checkout",
-  metadata: { traceId: trace.trace_id, sessionId: session_id, routeTemplate: route_template }
-)
-client.action(
-  "evt_action_checkout_submit",
-  "2026-06-02T10:00:03Z",
-  LogBrew::ProductTimeline.product_action(
-    name: "checkout.submit",
-    route_template: "/checkout/:cart_id",
-    session_id: session_id,
-    trace_id: trace.trace_id,
-    screen: "Checkout",
-    funnel: "checkout",
-    step: "submit"
-  )
-)
-client.metric(
-  "evt_metric_http_server_duration",
-  "2026-06-02T10:00:05Z",
-  name: "http.server.duration",
-  kind: "histogram",
-  value: 183.4,
-  unit: "ms",
-  temporality: "delta",
-  metadata: { method: "POST", routeTemplate: route_template, statusCode: 202, traceId: trace.trace_id }
+request_context = LogBrew::TelemetryContext.create
+  .with_session(id: session_id)
+  .with_subject(id: "subject_checkout_123", kind: "user")
+  .with_tag("journey", "checkout")
+  .build
+active_trace = LogBrew::Trace.create(
+  trace_id: trace.trace_id,
+  span_id: child_span_id,
+  parent_span_id: trace.parent_span_id,
+  trace_flags: trace.trace_flags
 )
-client.span(
-  "evt_span_checkout_request",
-  "2026-06-02T10:00:06Z",
-  LogBrew::Traceparent.span_attributes_from_traceparent(
-    trace,
-    LogBrew::TraceparentSpanInput.new(
-      name: "POST /checkout/:cart_id",
-      span_id: child_span_id,
-      duration_ms: 183.4,
-      metadata: { sampled: trace.sampled, routeTemplate: route_template, sessionId: session_id }
+
+LogBrew::Telemetry.with_context(request_context) do
+  LogBrew::Trace.with_context(active_trace) do
+    client.log(
+      "evt_log_checkout_started",
+      "2026-06-02T10:00:02Z",
+      message: "checkout request started",
+      level: "info",
+      logger: "checkout",
+      metadata: { routeTemplate: route_template }
     )
-  )
-)
+    client.action(
+      "evt_action_checkout_submit",
+      "2026-06-02T10:00:03Z",
+      LogBrew::ProductTimeline.product_action(
+        name: "checkout.submit",
+        route_template: route_template,
+        session_id: session_id,
+        trace_id: trace.trace_id,
+        screen: "Checkout",
+        funnel: "checkout",
+        step: "submit"
+      )
+    )
+    client.metric(
+      "evt_metric_http_server_duration",
+      "2026-06-02T10:00:05Z",
+      name: "http.server.duration",
+      kind: "histogram",
+      value: 183.4,
+      unit: "ms",
+      temporality: "delta",
+      metadata: { method: "POST", routeTemplate: route_template, statusCode: 202 }
+    )
+    client.span(
+      "evt_span_checkout_request",
+      "2026-06-02T10:00:06Z",
+      LogBrew::Traceparent.span_attributes_from_traceparent(
+        trace,
+        LogBrew::TraceparentSpanInput.new(
+          name: "POST /checkout/:cart_id",
+          span_id: child_span_id,
+          duration_ms: 183.4,
+          metadata: { sampled: trace.sampled, routeTemplate: route_template }
+        )
+      )
+    )
+  end
+end
 
 outgoing_headers = LogBrew::Traceparent.create_headers(
   trace_id: trace.trace_id,
@@ -250,7 +340,11 @@ outgoing_headers = LogBrew::Traceparent.create_headers(
 )
 ```
 
-The packaged `examples/first_useful_telemetry.rb` file shows the full flow, including release, environment, and network milestone events. Route templates stay query-free, metadata is primitive-only, and the SDK does not capture request bodies or arbitrary transport metadata.
+The packaged `examples/first_useful_telemetry.rb` file shows the full flow,
+including client resource/deployment context, release, environment, opaque
+subject/session correlation, and a network milestone. Route templates stay
+query-free, metadata is primitive-only, and the SDK does not capture request
+bodies or arbitrary transport metadata.
 
 ## W3C Trace Context
 
@@ -344,6 +438,63 @@ Both adapters are literal pass-throughs when `LogBrew::Trace.current` is absent.
 
 Outbound HTTP spans allow only method, normalized host, status code, duration, adapter source, sampled state, and exception type. They never record scheme, port, path, query, fragment, full URL, request or response headers, bodies or sizes, exception messages or stacks, authentication material, cookies, baggage, tracestate, resolved addresses, or arbitrary request options.
 
+## Typed Issue Diagnostics
+
+Use `LogBrew::IssueDiagnostics` when an application wants issue evidence that a
+human or coding agent can understand without parsing a flattened metadata map:
+
+```ruby
+breadcrumbs = [
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:58.125Z",
+    category: "checkout.navigation",
+    type: "navigation",
+    message: "User reached payment review",
+    data: { step: "payment" }
+  ),
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:59Z",
+    category: "checkout.request",
+    level: "warn",
+    data: { method: "POST", statusCode: 503 }
+  )
+]
+
+begin
+  checkout.call
+rescue RuntimeError => error
+  client.issue(
+    "evt_checkout_failure",
+    Time.now.utc.iso8601,
+    LogBrew::IssueDiagnostics.from_exception(
+      error,
+      message: "Checkout could not be completed.",
+      mechanism_type: "ruby.exception",
+      handled: true,
+      context: request_context,
+      metadata: { routeTemplate: "/checkout/:cart_id" },
+      breadcrumbs: breadcrumbs
+    )
+  )
+end
+```
+
+The typed payload exposes exception type, mechanism and handled state, up to 32
+newest-first stack frames, and up to 64 oldest-to-newest breadcrumbs. Generated
+frames contain only basename, positive coordinates, and bounded function
+identity. Explicit frames can also carry module, `inApp`, and debug ID. A
+breadcrumb accepts a stable category/type, normalized level, bounded message,
+and at most eight flat finite primitive data values. Set
+`breadcrumbs_truncated: true` when the supplied list omits earlier history.
+
+`from_exception` deliberately omits exception text unless `message:` is
+provided. Pass `context:` to correlate the issue with the same typed resource,
+trace, session, opaque subject, and tags as its surrounding signals. Automatic
+and manual structured frame projection never captures raw backtrace strings,
+source code, locals, arguments, or absolute paths. The raw Rails/Rack backtrace
+option is separate and remains off by default. Run
+`make -C examples run-issue-diagnostics` for a complete inspectable payload.
+
 ## Metrics
 
 Use `metric` for explicit, application-owned measurements. LogBrew validates the metric name, kind, value, unit, temporality, and optional metadata before queueing the event:
@@ -353,6 +504,7 @@ client.metric(
   "evt_metric_queue_depth",
   "2026-06-02T10:00:06Z",
   name: "queue.depth",
+  description: "Number of items waiting in the checkout queue.",
   kind: "gauge",
   value: 42,
   unit: "{items}",
@@ -361,7 +513,7 @@ client.metric(
 )
 ```
 
-Supported metric kinds are `counter`, `gauge`, and `histogram`. Counters and histograms require `delta` or `cumulative` temporality and non-negative values; gauges require `instant` temporality and may be negative. Keep metadata low-cardinality and primitive. This SDK does not automatically collect Ruby runtime, Rack, Rails, or database metrics yet.
+Supported metric kinds are `counter`, `gauge`, and `histogram`. Counters and histograms require `delta` or `cumulative` temporality and non-negative values; gauges require `instant` temporality and may be negative. An optional `description` gives people and investigation tools the stable meaning of the measurement. Keep it generic, single-line, between 1 and 1,024 Unicode scalar values, and free of identifiers, personal data, or changing values. It is not a query dimension. Keep metadata low-cardinality and primitive. This SDK does not automatically collect Ruby runtime, Rack, Rails, or database metrics yet.
 
 ## Product And Network Timelines
 
@@ -576,7 +728,10 @@ Event files contain the same validated event JSON your application submitted, in
 
 ## Example Source
 
-The `examples` directory contains copyable snippets for creating a client, sending through `HttpTransport`, using the standard logger wrapper, attaching Rack middleware, and subscribing to Rails errors in your own Ruby app.
+The `examples` directory contains copyable snippets for creating a client,
+building typed issue diagnostics, sending through `HttpTransport`, using the
+standard logger wrapper, attaching Rack middleware, and subscribing to Rails
+errors in your own Ruby app.
 
 ## Standard Logger
 
@@ -641,13 +796,14 @@ app = LogBrew::RackMiddleware.new(
 ```
 
 The manual middleware records successful responses as span events, records
-unhandled app exceptions as issue plus error-span events, and re-raises app
-exceptions so Rack keeps normal response handling. Its compatibility defaults
-retain path, request-ID, and exception-message capture. Set
-`include_exception_message: false` for type-only issues. Exception backtrace
-text is omitted unless `include_exception_backtrace: true` is set. Events queue
-by default; pass `transport:` plus `flush_on_response: true` when each response
-should flush.
+unhandled app exceptions as typed issue plus error-span events, and re-raises
+the exact app exception so Rack keeps normal response handling. Escaped issues
+use `rack.middleware`, `handled: false`, and bounded structured frames. Its
+compatibility defaults retain path, request-ID, and exception-message capture.
+Set `include_exception_message: false` for type-only issues. Raw backtrace text
+is omitted unless `include_exception_backtrace: true` is set; sanitized
+structured frames remain available either way. Events queue by default; pass
+`transport:` plus `flush_on_response: true` when each response should flush.
 
 ## Rails Error Subscriber
 
@@ -676,9 +832,11 @@ Rails.error.subscribe(
 ```
 
 The manual subscriber implements
-`report(error, handled:, severity:, context:, source:, **options)`. Its
-compatibility default includes primitive context values and exception messages;
-set `include_exception_message: false` for type-only issues. Backtrace text is
+`report(error, handled:, severity:, context:, source:, **options)`. Exception
+reports include typed identity, `rails.error_reporter`, the supplied handled
+state, and bounded structured frames. Its compatibility default includes
+primitive context values and exception messages; set
+`include_exception_message: false` for type-only issues. Raw backtrace text is
 omitted unless `include_exception_backtrace: true` is set. If you also use the
 manual Rack middleware, keep this subscriber focused on handled reports so
 unhandled request exceptions are not captured twice.
@@ -694,6 +852,7 @@ unhandled request exceptions are not captured twice.
 - `metric(...)` queues explicit, application-owned metric events with name, kind, value, unit, temporality, and low-cardinality metadata validation.
 - `LogBrew::ProductTimeline` builds explicit, application-owned product action and network milestone timeline events with primitive metadata and query/hash-free routes.
 - `LogBrew::SupportTicketDraft.create` builds explicit, local-only support-ticket create payload drafts with redacted diagnostics and no backend route calls.
+- `LogBrew::IssueDiagnostics` builds typed exception identity, mechanism/handled state, basename-only structured frames, and bounded ordered breadcrumbs without raw exception internals.
 - `LogBrew::HttpTransport` sends queued batches through Ruby's standard `Net::HTTP` with configurable endpoint, headers, timeout, and app-owned HTTP client support.
 - `LogBrew::RackMiddleware` captures Rack request spans and unhandled app exceptions without requiring Rails or Rack at runtime.
 - `LogBrew::RailsErrorSubscriber` captures handled/manual Rails error reports without requiring Rails at runtime.

data/examples/Makefile

@@ -1,10 +1,11 @@
-.PHONY: help run run-readme-example run-real-user-smoke run-first-useful-telemetry run-http-trace-correlation run-persistent-worker-delivery run-automatic-delivery run-sidekiq-tracing
+.PHONY: help run run-readme-example run-real-user-smoke run-first-useful-telemetry run-issue-diagnostics run-http-trace-correlation run-persistent-worker-delivery run-automatic-delivery run-sidekiq-tracing
 
 help:
 	@printf '%s\n' 'run-readme-example -> make run-readme-example'
 	@printf '%s\n' 'run (real-user-smoke) -> make run'
 	@printf '%s\n' 'run-real-user-smoke -> make run-real-user-smoke'
 	@printf '%s\n' 'run-first-useful-telemetry -> make run-first-useful-telemetry'
+	@printf '%s\n' 'run-issue-diagnostics -> make run-issue-diagnostics'
 	@printf '%s\n' 'run-http-trace-correlation -> make run-http-trace-correlation'
 	@printf '%s\n' 'run-persistent-worker-delivery -> make run-persistent-worker-delivery'
 	@printf '%s\n' 'run-automatic-delivery -> make run-automatic-delivery'
@@ -21,6 +22,9 @@ run-real-user-smoke:
 run-first-useful-telemetry:
 	@ruby first_useful_telemetry.rb
 
+run-issue-diagnostics:
+	@ruby issue_diagnostics.rb
+
 run-http-trace-correlation:
 	@ruby http_trace_correlation.rb
 

data/examples/first_useful_telemetry.rb

@@ -13,97 +13,115 @@ outgoing_headers = LogBrew::Traceparent.create_headers(
 )
 session_id = "sess_checkout_123"
 route_template = "/checkout/:cart_id"
+service_resource = LogBrew::TelemetryResource.create
+  .with_service(name: "checkout-service", version: "1.2.3")
+  .with_deployment(environment: "production", release: "checkout@1.2.3")
+  .with_framework(name: "rack")
+  .build
+service_context = LogBrew::TelemetryContext.create
+  .with_resource(service_resource)
+  .with_tag("region", "global")
+  .build
+request_context = LogBrew::TelemetryContext.create
+  .with_session(id: session_id)
+  .with_subject(id: "subject_checkout_123", kind: "user")
+  .with_tags("journey" => "checkout", "surface" => "payment")
+  .build
+active_trace = LogBrew::Trace.create(
+  trace_id: trace_context.trace_id,
+  span_id: child_span_id,
+  parent_span_id: trace_context.parent_span_id,
+  trace_flags: trace_context.trace_flags
+)
 
 client = LogBrew::Client.create(
   api_key: "LOGBREW_API_KEY",
   sdk_name: "checkout-service",
-  sdk_version: "1.2.3"
+  sdk_version: "1.2.3",
+  context: service_context
 )
 client.release(
   "evt_release_checkout",
   "2026-06-02T10:00:00Z",
   version: "1.2.3",
-  commit: "abc123def456",
-  metadata: { service: "checkout-service" }
+  commit: "abc123def456"
 )
 client.environment(
   "evt_environment_checkout",
   "2026-06-02T10:00:01Z",
   name: "production",
-  region: "global",
-  metadata: { service: "checkout-service" }
-)
-client.log(
-  "evt_log_checkout_started",
-  "2026-06-02T10:00:02Z",
-  message: "checkout request started",
-  level: "info",
-  logger: "checkout",
-  metadata: {
-    traceId: trace_context.trace_id,
-    sessionId: session_id,
-    routeTemplate: route_template
-  }
-)
-client.action(
-  "evt_action_checkout_submit",
-  "2026-06-02T10:00:03Z",
-  LogBrew::ProductTimeline.product_action(
-    name: "checkout.submit",
-    route_template: "https://shop.example/checkout/:cart_id?coupon=sample#review",
-    session_id: session_id,
-    trace_id: trace_context.trace_id,
-    screen: "Checkout",
-    funnel: "checkout",
-    step: "submit",
-    metadata: { cartTier: "gold" }
-  )
-)
-client.action(
-  "evt_action_payment_api",
-  "2026-06-02T10:00:04Z",
-  LogBrew::ProductTimeline.network_milestone(
-    route_template: "https://api.example/payments/:payment_id?card=sample",
-    method: "post",
-    status_code: 202,
-    duration_ms: 183.4,
-    session_id: session_id,
-    trace_id: trace_context.trace_id,
-    metadata: { dependency: "payments" }
-  )
+  region: "global"
 )
-client.metric(
-  "evt_metric_http_server_duration",
-  "2026-06-02T10:00:05Z",
-  name: "http.server.duration",
-  kind: "histogram",
-  value: 183.4,
-  unit: "ms",
-  temporality: "delta",
-  metadata: {
-    method: "POST",
-    routeTemplate: route_template,
-    statusCode: 202,
-    traceId: trace_context.trace_id
-  }
-)
-client.span(
-  "evt_span_checkout_request",
-  "2026-06-02T10:00:06Z",
-  LogBrew::Traceparent.span_attributes_from_traceparent(
-    trace_context,
-    LogBrew::TraceparentSpanInput.new(
-      name: "POST /checkout/:cart_id",
-      span_id: child_span_id,
-      duration_ms: 183.4,
+LogBrew::Telemetry.with_context(request_context) do
+  LogBrew::Trace.with_context(active_trace) do
+    client.log(
+      "evt_log_checkout_started",
+      "2026-06-02T10:00:02Z",
+      message: "checkout request started",
+      level: "info",
+      logger: "checkout",
+      metadata: { routeTemplate: route_template }
+    )
+    client.action(
+      "evt_action_checkout_submit",
+      "2026-06-02T10:00:03Z",
+      LogBrew::ProductTimeline.product_action(
+        name: "checkout.submit",
+        route_template: "https://shop.example/checkout/:cart_id?coupon=sample#review",
+        session_id: session_id,
+        trace_id: trace_context.trace_id,
+        screen: "Checkout",
+        funnel: "checkout",
+        step: "submit",
+        metadata: { cartTier: "gold" }
+      )
+    )
+    client.action(
+      "evt_action_payment_api",
+      "2026-06-02T10:00:04Z",
+      LogBrew::ProductTimeline.network_milestone(
+        route_template: "https://api.example/payments/:payment_id?card=sample",
+        method: "post",
+        status_code: 202,
+        duration_ms: 183.4,
+        session_id: session_id,
+        trace_id: trace_context.trace_id,
+        metadata: { dependency: "payments" }
+      )
+    )
+    client.metric(
+      "evt_metric_http_server_duration",
+      "2026-06-02T10:00:05Z",
+      name: "http.server.duration",
+      description: "Duration of one completed server request.",
+      kind: "histogram",
+      value: 183.4,
+      unit: "ms",
+      temporality: "delta",
       metadata: {
-        sampled: trace_context.sampled,
+        method: "POST",
         routeTemplate: route_template,
-        sessionId: session_id
+        statusCode: 202
       }
     )
-  )
-)
+    client.span(
+      "evt_span_checkout_request",
+      "2026-06-02T10:00:06Z",
+      LogBrew::Traceparent.span_attributes_from_traceparent(
+        trace_context,
+        LogBrew::TraceparentSpanInput.new(
+          name: "POST /checkout/:cart_id",
+          span_id: child_span_id,
+          duration_ms: 183.4,
+          metadata: {
+            sampled: trace_context.sampled,
+            routeTemplate: route_template
+          }
+        )
+      )
+    )
+  end
+end
 
 puts client.preview_json
 

data/examples/http_trace_correlation.rb

@@ -61,6 +61,7 @@ app = lambda do |env|
     "evt_metric_checkout_trace",
     "2026-06-02T10:00:05Z",
     name: "http.server.duration",
+    description: "Duration of one completed server request.",
     kind: "histogram",
     value: 183.4,
     unit: "ms",

data/examples/issue_diagnostics.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "json"
+require "logbrew"
+
+module CheckoutFailureFixture
+  def self.fail_checkout
+    raise RuntimeError, "sensitive provider response fixture"
+  end
+end
+
+client = LogBrew::Client.create(
+  api_key: "LOGBREW_API_KEY",
+  sdk_name: "checkout-ruby-service",
+  sdk_version: "1.4.2"
+)
+breadcrumbs = [
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:58.125+00:00",
+    category: "checkout.navigation",
+    type: "navigation",
+    level: "info",
+    message: "User reached payment review",
+    data: { step: "payment" }
+  ),
+  LogBrew::IssueDiagnostics.breadcrumb(
+    timestamp: "2026-08-02T10:14:59Z",
+    category: "checkout.request",
+    type: "http",
+    level: "warn",
+    data: { method: "POST", statusCode: 503 }
+  )
+]
+
+begin
+  CheckoutFailureFixture.fail_checkout
+rescue RuntimeError => error
+  client.issue(
+    "evt_issue_checkout_failure",
+    "2026-08-02T10:15:00Z",
+    LogBrew::IssueDiagnostics.from_exception(
+      error,
+      message: "Checkout could not be completed.",
+      mechanism_type: "ruby.exception",
+      handled: true,
+      metadata: { routeTemplate: "/checkout/:cart_id" },
+      breadcrumbs: breadcrumbs
+    )
+  )
+end
+
+puts client.preview_json
+
+response = client.shutdown(LogBrew::RecordingTransport.always_accept)
+warn JSON.generate(ok: true, status: response.status_code, events: 1)