fix(runtime): flush pending telemetry at process exit

[kxzk]

TL;DR

Normal process exit now flushes queued Langfuse spans and scores automatically.

Why

Short-lived tasks and one-off scripts could exit before SDK background workers delivered pending telemetry.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

Note

Kade's words:

Summary

Normal process exit now flushes pending spans and scores. Applications do not need to register their own at_exit callback. Explicit Langfuse.shutdown and Langfuse.reset! disable the pending callback for the current lifecycle.

The callback runs once and catches shutdown errors. The callback inherits the fork-safe synchronization from the base PR. This PR targets the fork-safety branch so the unsafe exit-only behavior cannot land first.

Change diagram

flowchart LR
    accTitle: Automatic telemetry flush during process exit
    accDescr: A normal process exit runs one SDK callback that flushes queued spans and scores without allowing errors to escape.
    E["Normal process exit"] --> H["Run one SDK callback"]
    H --> T["Flush pending spans"]
    H --> S["Flush pending scores"]
    H --> G["Catch shutdown errors"]
    X["Explicit SDK shutdown"] --> D["Disable pending callback"]

Loading

Verification

I ran the complete RSpec suite locally. All 1,581 examples passed. Line coverage was 96.51%.

I ran RuboCop against 101 files. RuboCop reported no offenses.

I ran a separate Ruby process with the SDK and did not call Langfuse.shutdown. The process exited normally. The exit callback delivered trace 93999b473b9b9d18d22d0e1537004e64 and its queued sdk-exit-hook score. The Langfuse CLI read back both records.

I did not test abrupt termination because SIGKILL cannot run process-exit callbacks. I did not preview the rendered Mermaid diagram in GitHub. I reviewed the Mermaid source and syntax locally.

---

Note

Medium Risk
Changes global process exit and configuration assignment behavior; failures are contained but every configured process now attempts shutdown on exit.

Overview
Adds automatic flushing of pending spans and scores on normal process exit, so scripts and short-lived processes no longer need their own at_exit { Langfuse.shutdown }.

A new Langfuse::ExitHook registers a single Kernel.at_exit callback that runs Langfuse.shutdown once, swallows shutdown errors (warns instead), and resets its mutex after fork via ForkSafety. The hook is enabled when configuration is first built (configuration / configuration=) and disabled by explicit Langfuse.shutdown or Langfuse.reset! so double-flush is avoided. Assigning configuration= now calls reset! first and starts a fresh lifecycle.

CONFIGURATION.md documents the Process Exit behavior and updates the shutdown example away from manual at_exit.

^{Reviewed by Cursor Bugbot for commit f380f48. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

AAI-388

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 29cf976. Configure here.}