julewire-core 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e20df02ec73ceafd282ab52015e46a28f9aa7b1d69461e2622afc301f9e98d40
+  data.tar.gz: 4e12bb12f787534aa5318084f6fa69fc1888590d85874d253c12dbfc6d6701f7
+SHA512:
+  metadata.gz: 222e5041e3d984b1e3d50a989c461522cf7622257d1698e7e9fdee9f10f2837537a883fbfe16466ac31abf868558807e1a07642e52c894ac020bf71c628a1896
+  data.tar.gz: 75f19494c48c6d46ae6bdf997db3605abc93323180589804d0e6338e1c7e592cd58150fbef9be4ccb5bfba577fb1086745ee8b779b6588aa7996572a55a5563f

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## Unreleased
+
+## 1.0.0 - 2026-06-21
+
+- Initial release: execution-scoped structured logging, propagation, bounded
+  serialization, processors, destinations, health, tail, doctor, and CLI.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexander Grebennik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,73 @@
+# Julewire Core
+
+`julewire-core` is the synchronous structured logging runtime behind Julewire.
+
+It builds provider-neutral records, execution context, propagated carry,
+non-propagated attributes, final summaries, processor chains, and synchronous
+direct outputs. It does not know about app frameworks, privacy policy, provider
+schemas, async queues, or delivery.
+
+## Install
+
+```ruby
+gem "julewire-core"
+```
+
+## Quickstart
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(:default, output: $stdout)
+end
+
+Julewire.with_execution(type: :job, id: "job-1") do
+  Julewire.context.add(tenant_id: "tenant-1")
+  Julewire.summary.increment(:records_seen)
+
+  Julewire.measure(:process_record) do
+    Julewire.emit("processed record", id: 123)
+  end
+end
+```
+
+By default, direct output is newline-delimited JSON.
+
+## Field Bags
+
+| Bag | Use it for | Propagates? | Default JSON? |
+| --- | --- | --- | --- |
+| `context` | queryable facts copied onto records in the current scope | yes | yes |
+| `carry` | hidden forwarding metadata for integrations and formatters | yes | no |
+| `neutral` | provider-neutral formatter-coordination facts | no | no |
+| `attributes` | integration and application namespaces | no | yes |
+| `summary` | final-only counters, timings, and completion facts | no | summary only |
+| `labels` | operator-safe routing/grouping metadata | no | yes |
+| `metrics` | numeric measurements such as duration | no | yes |
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Configuration](docs/configuration.md)
+- [Advanced Configuration](docs/advanced-configuration.md)
+- [Context and Propagation](docs/context-and-propagation.md)
+- [Instrumentation Cheatsheet](docs/instrumentation-cheatsheet.md)
+- [Attribute Keys](docs/attribute-keys.md)
+- [Records and Data Policy](docs/records-and-data-policy.md)
+- [Outputs and Lifecycle](docs/outputs-and-lifecycle.md)
+- [Developer Tail](docs/tail.md)
+- [Health Schema](docs/health-schema.md)
+- [Security and Wire Keys](docs/security-and-wire.md)
+- [Extension Contracts](docs/contracts.md)
+- [Extensions and API](docs/extensions-and-api.md)
+- [Record Sources](docs/record-sources.md)
+- [Internals](docs/internals.md)
+- [Development](docs/development.md)
+
+## Runtime Promise
+
+Julewire is best-effort logging infrastructure. `StandardError` failures inside
+Julewire's own normalization, processing, formatting, encoding, and output path
+are contained so application code keeps running.
+
+Core stays synchronous. Custom destinations own async queues, files, fanout,
+batching, retries, and delivery health.

data/docs/advanced-configuration.md

@@ -0,0 +1,66 @@
+# Advanced Configuration
+
+## Runtime Configuration
+
+`configure` yields a mutable `Julewire::Core::Configuration` builder, then
+stores a frozen copy with frozen registry containers. Core builds and installs
+the staged pipeline against that frozen copy before swapping runtime state.
+
+The active configuration containers exposed by `Julewire.config` and
+`Julewire.labels` are read-only. Mutating runtime configuration after the fact
+is unsupported. Call `Julewire.configure` again.
+
+User-supplied destination formatter, encoder, output, and processor instances
+are shared by reference. Processors, formatters, and encoders must be stateless
+or otherwise reentrant; core does not synchronize them. Direct outputs are
+wrapped with a per-destination mutex.
+
+When a reconfigure reuses the same output or destination object, core keeps that
+resource open for the new active pipeline and skips teardown through the old
+pipeline. Replacing an output object still flushes or closes the previous one
+according to its `close_output` setting.
+
+`configure` is non-reentrant. Do not call runtime APIs such as `emit`,
+`configure`, or `reset!` from inside a `configure` block.
+
+## Failure and Drop Callbacks
+
+`on_failure` receives contained `StandardError` instances from Julewire's own
+logging path, plus one metadata hash. Metadata may include `:phase`,
+`:record_metadata`, `:action`, and output class when known.
+
+`on_drop` receives a symbolic reason for operational drops after processing has
+started, such as oversized encoded records, formatter errors, encoder errors,
+output failures, output rejections, custom destination failures/rejections, and
+post-close `:runtime_closed` drops.
+
+Level filtering and intentional no-output mode are counted in health but do not
+call `on_drop`; those are configuration or policy outcomes, not output-loss
+callbacks. Drop callbacks receive the same metadata-hash shape.
+
+Callbacks are best effort. Exceptions raised by callbacks are swallowed and
+counted where health can report them. Core health keeps those counters small;
+callbacks that need richer diagnostics should record them locally.
+The recursion guard uses fiber storage, so work handed to a child fiber from
+inside a callback stays inside the same callback-suppression scope.
+
+Callbacks are called with two positional arguments:
+`on_failure.call(error, metadata)` and `on_drop.call(reason, metadata)`.
+Core uses Ruby duck typing at configuration time; it only requires callback
+objects to respond to `call`. Arity or keyword mistakes are contained when the
+callback is invoked and are counted as callback failures in health.
+
+Drop counters count every dropped record. Use health counters for alerting;
+callback frequency is intentionally not a metric. Applications that need
+callback throttling should implement it in the callback.
+
+## Non-Standard Exception Summaries
+
+`emit_non_standard_exception_summaries` defaults to `false`.
+
+When false, core suppresses execution summaries while unwinding exceptions
+outside `StandardError`, such as `SystemExit` and signal exceptions. When true,
+core tries to emit those summaries too.
+
+The application exception still wins; execution boundaries re-raise application
+exits after recording what they can.

data/docs/attribute-keys.md

@@ -0,0 +1,74 @@
+# Attribute Keys
+
+Attributes are record-local fields for integrations, processors, and
+formatters. They do not propagate. Integration-specific detail belongs under a
+namespace such as `attributes.web`, `attributes.job`, or
+`attributes.messaging`; those namespaces are emitted by default.
+
+Neutral keys are formatter coordination fields stored in the record's `neutral`
+section. Formatters can promote them to provider-native output, but the default
+formatter strips the section from emitted JSON so the same fact is not logged
+twice. User attributes such as `my_app.some_key` remain normal emitted
+attributes.
+
+Neutral keys track current OpenTelemetry semantic-convention names where those
+names fit Julewire records. Julewire intentionally follows current/edge names
+instead of pinning this page to one semconv release. Julewire still owns this
+contract: upstream semconv changes make a key worth rechecking, not
+automatically emitted.
+
+## HTTP
+
+| Key | Meaning |
+| --- | --- |
+| `http.request.method` | HTTP request method. |
+| `url.full` | Full filtered request URL when available. |
+| `url.path` | Request path. |
+| `http.response.status_code` | HTTP response status. |
+| `user_agent.original` | Raw user-agent value. |
+| `client.address` | Client address or remote IP. |
+| `http.response.body.size` | Response body size in bytes. |
+
+## Code
+
+| Key | Meaning |
+| --- | --- |
+| `code.file.path` | Source file path. |
+| `code.line.number` | Source line number. |
+| `code.function.name` | Source function, method, or label. |
+
+## Jobs
+
+Current OpenTelemetry semconv does not provide a general job namespace that fits
+ActiveJob-style execution summaries, so these are Julewire neutral job keys.
+
+| Key | Meaning |
+| --- | --- |
+| `job.system` | Job framework or runtime, such as `active_job`. |
+| `job.name` | Job class or logical job name. |
+| `job.id` | Framework job id. |
+| `job.provider_id` | Backend provider job id. |
+| `job.queue.name` | Queue name. |
+| `job.priority` | Queue priority. |
+| `job.execution_count` | Framework execution count or attempt count. |
+| `job.enqueued_at` | Enqueue timestamp. |
+| `job.scheduled_at` | Scheduled timestamp. |
+| `job.status` | Summary status such as `ok` or `error`. |
+
+## Messaging
+
+| Key | Meaning |
+| --- | --- |
+| `messaging.system` | Messaging system, such as `kafka`. |
+| `messaging.operation.name` | Operation name from the integration event. |
+| `messaging.operation.type` | Generic type such as `process`, `receive`, or `send`. |
+| `messaging.destination.name` | Topic, stream, or queue name. |
+| `messaging.destination.partition.id` | Partition id. |
+| `messaging.batch.message_count` | Message count in a batch. |
+| `messaging.consumer.group.name` | Consumer group name. |
+| `messaging.kafka.offset` | Kafka offset. |
+| `messaging.kafka.message.key` | Kafka message key. |
+
+Formatters should read neutral keys from `record.neutral` when producing
+provider-native fields. They should not inspect integration-specific namespaces
+unless they explicitly document that integration coupling.

data/docs/configuration.md

@@ -0,0 +1,327 @@
+# Configuration
+
+`Julewire.configure` is the only mutation path for runtime configuration:
+
+```ruby
+Julewire.configure do |config|
+  config.level = :info
+  config.destinations.use(
+    :default,
+    formatter: Julewire::RecordFormatter.new,
+    output: $stdout,
+    close_output: false
+  )
+
+  config.labels.add(service: "billing", env: "production")
+
+  config.on_failure = ->(error, metadata) {
+    warn("julewire failure phase=#{metadata[:phase]} error=#{error.class}")
+  }
+
+  config.on_drop = ->(reason, metadata) {
+    warn("julewire dropped reason=#{reason} phase=#{metadata[:phase]}")
+  }
+end
+```
+
+## Core Settings
+
+| Setting | Meaning |
+| --- | --- |
+| `level` | Global minimum severity. Defaults to `:debug`. |
+| `pipeline_close_timeout` | Default timeout for pipeline close. Defaults to `1`. |
+| `emit_non_standard_exception_summaries` | Emit summaries while unwinding `SystemExit`/signals. Defaults to `false`. |
+| `error_backtrace_lines` | Exception backtrace line cap. Defaults to `20`; set `0` to omit backtraces. |
+| `labels` | Static labels merged into every record. |
+| `processors` | Chain that mutates/enriches records before formatting. |
+| `destinations` | Named formatter/encoder/output graph or custom destinations. |
+| `on_failure` | Best-effort callback for contained core failures. |
+| `on_drop` | Best-effort callback for operational drops after a record reaches destination/output handling. |
+
+Timeout values must be `nil` or non-negative finite numerics.
+`error_backtrace_lines` must be a non-negative integer.
+
+`error_backtrace_lines` applies at core's error-shaping boundaries. When a
+record enters core with an `Exception` under `error`, core builds the error hash
+with that limit before the record is frozen. When a formatter/serializer later
+sees an `Exception`, it applies the same limit while shaping it. Integrations
+should pass real `Exception` objects or core-shaped error hashes; core also
+trims `backtrace` fields on those error hashes at record ingress so a forgotten
+adapter limit cannot leak a full stack by accident.
+
+Async queues, files, fanout, batching, retries, and delivery policy belong in
+custom destinations. Core owns sync destination writes only.
+
+## Levels
+
+Supported severities:
+
+```ruby
+debug info warn error fatal unknown
+```
+
+Core accepts symbols, strings, and stdlib `Logger::Severity` integers. String
+and symbol names are case-insensitive.
+
+Records with eager severity below `config.level` are dropped before context
+lookup, processors, formatting, and output writes. For lazy `emit` blocks with
+no eager severity, core evaluates the block first, then applies the level check
+to the final record.
+
+When `Julewire.emit` receives both a positional hash and keyword fields, keyword
+fields win for duplicate top-level keys before record normalization. In lazy
+emits, the block result wins over eager non-severity fields; an eager severity
+from a severity helper such as `Julewire.warn` remains authoritative.
+
+## Static Labels
+
+```ruby
+Julewire.configure do |config|
+  config.labels.add(service: "billing")
+  config.labels.remove(:debug_label)
+  config.labels.clear
+end
+```
+
+Labels follow the core field contract: public helpers accept string or symbol
+keys and normalize strings to symbols at the boundary. Per-record labels
+override configured static labels with the same symbol key.
+
+Labels are meant for non-sensitive, low-cardinality dimensions such as service,
+environment, shard, region, or runtime. Core may copy labels into internal
+diagnostic records because labels are treated as operator-safe routing/grouping
+metadata. Do not put PII, secrets, or high-cardinality payload data in labels.
+
+## Processors
+
+Processors run before destinations:
+
+```ruby
+Julewire.configure do |config|
+  config.processors.use MyProcessor
+  config.processors.use MyProcessorWithArgs, "constructor-arg", enabled: true
+  config.processors.use EnrichmentProcessor, on_error: :fail_open
+  config.processors.prepend FirstProcessor
+  config.processors.use Julewire::Match.new { on(severity: :debug) { :drop } }
+  config.processors.use :sampling, rate: 0.1
+  config.processors.use do |draft|
+    draft[:attributes][:app] = { source: "app" }
+  end
+end
+```
+
+Core ships no default policy processors. It does include small processor
+helpers such as `Julewire::Match` and deterministic head sampling through the
+registered `:sampling` processor. Redaction and enrichment belong in
+processors. Output-specific shape belongs in destination formatters. Processors
+are the mutation stage.
+
+Processors receive the current `Julewire::RecordDraft`. Mutate the draft
+directly. Return `:drop` to stop delivery or a different `Julewire::RecordDraft` to
+replace the current draft; any other return value is ignored. Processors own
+the draft until the final record boundary, so direct mutation is the normal hot
+path:
+
+```ruby
+class AddTenantLabel
+  def call(draft)
+    tenant = draft.fetch(:context).fetch(:tenant_id, nil)
+    return unless tenant
+
+    draft[:labels][:tenant] = tenant
+  end
+end
+
+Julewire.configure do |config|
+  config.processors.prepend AddTenantLabel.new
+end
+```
+
+The `:sampling` processor hashes a deterministic key and returns `:drop` for
+unsampled records. By default it uses execution/root identifiers when present,
+then `context.request_id`, then deterministic record fields. Pass `key:` to choose an
+application-specific key:
+
+```ruby
+config.processors.use(
+  :sampling,
+  rate: 0.05,
+  key: ->(draft) { draft.dig(:context, :tenant_id) }
+)
+```
+
+Processor exceptions use the registration policy:
+
+| `on_error` | Behavior |
+| --- | --- |
+| `:fail_closed` | Default. Emit a `julewire.processor_error` replacement record and stop the chain. |
+| `:fail_open` | Record the failure, keep the current draft, and continue with later processors. |
+| `:drop` | Record the failure and suppress the record. |
+
+Public emit input remains defensive. The final immutable record boundary
+validates the Julewire record shape before destinations see it.
+
+Destination-local processors run after the global processor chain and before
+one destination formats the record. Use them for sink-specific policy such as
+audit-only enrichment or destination-only sampling:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(:stdout, output: $stdout)
+  config.destinations.use(
+    :audit,
+    output: audit_io,
+    processors: [
+      ->(draft) { draft[:labels][:sink] = "audit" }
+    ]
+  )
+end
+```
+
+A destination-local drop or processor failure affects only that destination.
+
+## Destinations
+
+Direct destinations pair a formatter, encoder, and output:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :default,
+    formatter: Julewire::RecordFormatter.new,
+    encoder: Julewire::JsonEncoder.new,
+    output: $stdout
+  )
+end
+```
+
+Integration gems may register destination kinds with adapter-specific options:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(:provider_json, output: $stdout)
+  config.destinations.use(:transport, formatter: formatter, io: $stdout)
+end
+```
+
+For local human-readable output, pair the console formatter with the text
+encoder:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :console,
+    formatter: Julewire::ConsoleFormatter.new,
+    encoder: Julewire::TextEncoder.new(color: $stdout.tty?),
+    output: $stdout
+  )
+end
+```
+
+For a loud local console, `Julewire.punk!` replaces the named runtime's
+destinations with the console formatter and the punk text theme:
+
+```ruby
+Julewire.punk!(color: $stdout.tty?)
+```
+
+For local containment drills, add `chaos: true`. It wraps the output with a
+small chaos sink that occasionally raises, rejects, or stalls writes so the
+runtime health path visibly degrades while application calls stay contained.
+
+```ruby
+Julewire.punk!(color: $stdout.tty?, chaos: true)
+```
+
+`Julewire.dev!` is the same core-local dev shape with a bounded in-memory tail
+attached:
+
+```ruby
+tail = Julewire.dev!(chaos: true, tail: { capacity: 500 })
+```
+
+Additional destinations are explicit:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.use(
+    :json_stdout,
+    formatter: Julewire::RecordFormatter.new,
+    encoder: Julewire::JsonEncoder.new,
+    output: $stdout
+  )
+
+  config.destinations.use(
+    :debug_file,
+    formatter: Julewire::RecordFormatter.new,
+    encoder: Julewire::JsonEncoder.new,
+    output: File.open("log/debug.json", "a"),
+    close_output: true
+  )
+end
+```
+
+Destination options:
+
+- `formatter`
+- `encoder`
+- `output`
+- `close_output`
+- `max_record_bytes` (defaults to `1 MiB`)
+- `on_failure`
+- `on_drop`
+- `processors`
+
+Extensions can also install an already-built destination object:
+
+```ruby
+config.destinations.add(MyDestination.new(name: :custom))
+```
+
+Custom destination objects must respond to `name`, `emit(record)`, `flush`,
+`close`, and `health`.
+
+`Julewire.configure` starts from the active configuration. To replace the output
+graph in a later configure call, clear destinations first:
+
+```ruby
+Julewire.configure do |config|
+  config.destinations.clear
+  config.destinations.use(:default, output: $stdout)
+end
+```
+
+## Split Pipelines
+
+The top-level `Julewire` facade uses the default runtime. Use named runtimes
+when one process needs separate pipeline policy, such as redacted stdout and a
+locked-down audit sink:
+
+```ruby
+Julewire.runtime(:audit).configure do |config|
+  config.destinations.use(:audit, output: audit_io)
+end
+
+Julewire.runtime(:audit).emit(message: "audit-only")
+```
+
+Named runtimes have their own configuration, processors, destinations, health,
+and close/flush lifecycle. `Julewire.after_fork!` resets every known runtime.
+
+Destinations receive the immutable processed `Julewire::Record`. Hashes,
+arrays, and copied strings inside the record are frozen; arbitrary app objects
+inside fields are not deep-frozen. Formatters must treat the record as read-only
+and return a payload object. Encoders turn formatter payloads into strings
+before writing to direct outputs. The default encoder is
+`Julewire::JsonEncoder`, which applies Julewire serialization before
+`JSON.generate`. A formatter that mutates frozen containers raises and is
+handled as a formatter failure.
+
+Destination callbacks inherit from the global callbacks unless overridden.
+
+For reconfigure semantics, callback details, and other low-level knobs, see
+[Advanced Configuration](advanced-configuration.md).
+
+Calling `Julewire.emit` from callbacks may still run the nested emit, but nested
+callback delivery is suppressed as callback recursion. Components that track
+callback failures count the suppression.