---
name: runtime-file-state-to-json
group: api
category: runtime
update-time: 20260512
description: Convert RuntimeFileState into a JSON value that combines file status with outer queue runtime metrics.
key-word:
    - runtime
    - file
    - state
    - public
---

## Runtime-file-state-to-json

Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and outer queue metrics for queued file runtime diagnostics.

### Interface

```moonbit
pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.JsonValue {}
```

#### input

- `state : RuntimeFileState` - Combined file and queue runtime snapshot.

#### output

- `JsonValue` - Structured JSON representation of the runtime file state.

### Explanation

Detailed rules explaining key parameters and behaviors

- The output includes `file`, `queued`, `pending_count`, and `dropped_count`.
- `file` is itself exported as a nested file sink state object.
- This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context.
- It is useful for `ConfiguredLogger::file_runtime_state()` and similar queued-file diagnostics flows.

### How to Use

Here are some specific examples provided.

#### When Need Structured Queued-file Diagnostics

When file and queue status should be exported together:
```moonbit
let value = runtime_file_state_to_json(snapshot)
```

In this example, callers receive a machine-readable combined runtime snapshot.

#### When Need Support Payload Composition

When queued file runtime data should be embedded into a larger JSON object:
```moonbit
let payload = runtime_file_state_to_json(state)
```

In this example, the helper keeps file-plus-queue diagnostics in one reusable JSON value.

### Error Case

e.g.:
- If `queued=false`, the state still serializes normally with queue counters present.

- If callers need direct text output, `stringify_runtime_file_state(...)` is the better API.

### Notes

1. Use this helper when file and queue runtime context should stay together.

2. It is especially useful for configured queued file loggers.