# `OCSF.Correlation`
[🔗](https://github.com/docjerem/ocsf/blob/v0.1.0/lib/ocsf/correlation.ex#L1)

Business-flow correlation scope.

Stores a `correlation_uid` in the process dictionary for the duration
of a function call. Every OCSF event created inside the scope
auto-stamps `metadata.correlation_uid` unless explicitly provided.
This enables tracing multiple events that belong to the same
business-level flow (e.g. a login attempt spanning preauth, logon,
and MFA steps).

## Examples

    OCSF.Correlation.with("corr-123", fn ->
      # all events created here get correlation_uid = "corr-123"
      OCSF.Correlation.current()
      #=> "corr-123"
    end)

See `OCSF.Metadata` for how `correlation_uid` is persisted on events.

# `clear`

```elixir
@spec clear() :: :ok
```

Clear the current correlation UID.

## Examples

    iex> OCSF.Correlation.clear()
    :ok

# `current`

```elixir
@spec current() :: String.t() | nil
```

Return the current correlation UID, or `nil` if none is set.

## Examples

    iex> OCSF.Correlation.current()
    nil

# `put`

```elixir
@spec put(String.t()) :: :ok
```

Set the current correlation UID.

## Examples

    iex> OCSF.Correlation.put("test-uid")
    :ok

# `with`

```elixir
@spec with(String.t(), (-> result)) :: result when result: var
```

Execute `fun` with `uid` as the current correlation UID, restoring the previous value on exit.

## Examples

    iex> OCSF.Correlation.with("abc", fn -> OCSF.Correlation.current() end)
    "abc"

---

*Consult [api-reference.md](api-reference.md) for complete listing*