# log

Streaming timestamped log messages to Core or journal files.

Like [`crate::stream::NominalDatasetStream`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/stream/struct.NominalDatasetStream.md "nominal_streaming::stream::NominalDatasetStream"), a log stream batches writes, applies
backpressure and delivers complete requests through a consumer. Logs use a separate
columnar wire representation and journal JSONL fallback. Their limits count encoded
protobuf bytes as well as records, since messages and arguments vary in size.

Example: recording to a journal

```rust
use std::collections::HashMap;
use nominal_streaming::log::NominalLogStream;

let stream = NominalLogStream::builder()
    .stream_to_file("logs")
    .build()?;
let writer = stream.log_writer("application", HashMap::new());
writer.push(1_789_392_441_123_456_789, "Started")?;
let stats = stream.close()?;
assert_eq!(stats.backed_up_records, 1);
```

For Core delivery, configure [`NominalLogStreamBuilder::stream_to_core`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStreamBuilder.md#method.stream_to_core "nominal_streaming::log::NominalLogStreamBuilder::stream_to_core") and
[`NominalLogStreamBuilder::with_file_fallback`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStreamBuilder.md#method.with_file_fallback "nominal_streaming::log::NominalLogStreamBuilder::with_file_fallback"). Keep the supplied multi-thread Tokio
runtime alive until close completes. These APIs block; use a blocking context in async code.

Enqueue accepts records into memory. [`NominalLogStream::flush`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStream.md#method.flush "nominal_streaming::log::NominalLogStream::flush") and
[`NominalLogStream::close`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStream.md#method.close "nominal_streaming::log::NominalLogStream::close") wait for delivery or preservation and report failures.
Acknowledged batches never go to fallback; an unconfirmed request may already exist in
Core, so retries or journal recovery can duplicate it. Buffered records are not crash-durable.

## Structs

- [`NominalLogStream`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStream.md "nominal_streaming::log::NominalLogStream"): A bounded log stream. Enqueue acknowledges memory acceptance, not remote durability.
- [`NominalLogStreamBuilder`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStreamBuilder.md "nominal_streaming::log::NominalLogStreamBuilder"): Configure a Core or file target and the log stream resource limits.
- [`NominalLogWriter`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogWriter.md "nominal_streaming::log::NominalLogWriter"): A channel writer with common per-record arguments.
- [`LogRecord`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.LogRecord.md "nominal_streaming::log::LogRecord"): One log event. Integer timestamps are signed nanoseconds since the Unix epoch.
- [`NominalLogStreamOpts`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.NominalLogStreamOpts.md "nominal_streaming::log::NominalLogStreamOpts"): Limits include ready and in-flight batches, so a stalled backend applies backpressure. Uploads use the same Conjure HTTP client and retry policy as time-series streaming. Construct with `Default` and customize its public fields before passing to the builder.
- [`LogStreamStats`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/struct.LogStreamStats.md "nominal_streaming::log::LogStreamStats"): Cumulative delivery outcomes. Backup is preservation on disk, not backend acknowledgement.

## Enums

- [`LogStreamError`](https://dev.nominal.io/nominal-streaming/ref/rust/nominal_streaming/log/enum.LogStreamError.md "nominal_streaming::log::LogStreamError")
