Environment Variables

Every variable below is optional. Most are read by FailureDiagnosticsConfig.from_env() at story construction time; two are read separately by the shared renderer-selection helper used by every auto-instrumentation entry point.

Diagnostics and analyzer variables

These are read by FailureDiagnosticsConfig.from_env().

Variable	Values	Default	Effect
`RUNTIME_NARRATIVE_ENV`	`development`, `production`	`development`	In `production`: traceback capped at 8 000 chars; `rich` forced to `lean` unless `RUNTIME_NARRATIVE_ALLOW_RICH_IN_PRODUCTION=1`
`RUNTIME_NARRATIVE_FAILURE_DIAGNOSTICS`	`lean`, `rich`	`lean`	`rich` captures local variables for up to 2 frames. Invalid values raise `ValueError` at story construction
`RUNTIME_NARRATIVE_ALLOW_RICH_IN_PRODUCTION`	`1`, `true`, `yes`, `on`	off	Permits `rich` diagnostics even when `RUNTIME_NARRATIVE_ENV=production`
`RUNTIME_NARRATIVE_MODEL`	model name string	—	Default model for `AnthropicFailureAnalyzer`; also read by `OllamaFailureAnalyzer` and `LLMFailureAnalyzer` (and example scripts) to select a model
`RUNTIME_NARRATIVE_ENDPOINT`	URL	—	Custom LLM endpoint for example scripts
`ANTHROPIC_API_KEY`	API key	—	Required by `AnthropicFailureAnalyzer` when `api_key=` is not passed explicitly; raises `ValueError` at construction if absent
`RUNTIME_NARRATIVE_ANALYZER_TIMEOUT_SECONDS`	seconds (float)	`12` (`OllamaFailureAnalyzer`/`LLMFailureAnalyzer`), `30` (`AnthropicFailureAnalyzer`)	Request timeout for the built-in failure analyzers. Raise it for slower or cold-loading local models (e.g. Ollama loading a multi-GB model from disk); on timeout or any other request failure the analyzer logs a `logging.warning` (module `runtime_narrative.analyzers.*`) and falls back to no LLM analysis rather than failing the story

Rich log file variables

These two are read separately, by runtime_narrative.renderer_defaults.default_renderers() — the renderer-selection helper shared by every auto-instrumentation entry point (RuntimeNarrativeMiddleware, the Django middleware, NarrativeTask/connect_narrative, the gRPC interceptors) when renderers is not passed explicitly. They have no effect when renderers= is set directly.

Variable	Values	Default	Effect
`RUNTIME_NARRATIVE_RICH_LOG_FILE`	file path	—	When set, adds a `ConsoleRenderer` writing the human-readable narrative to this file (append mode, opened once and kept open for the process lifetime), on top of whichever base renderer TTY detection selects
`RUNTIME_NARRATIVE_RICH_LOG_CONSOLE`	`1`, `0`	`1`	Only consulted when `RUNTIME_NARRATIVE_RICH_LOG_FILE` is set and stdout is a TTY. `0` stops also echoing the narrative to the terminal, so it goes to the file only

Precedence rules

Environment variables form the base layer. Programmatic kwargs override them.

python

import os
os.environ["RUNTIME_NARRATIVE_FAILURE_DIAGNOSTICS"] = "lean"

# Override for this specific story
with story(
    "My Story",
    failure_diagnostics="rich",          # wins over env var
    runtime_environment="development",
):
    ...

When diagnostics_config= is passed explicitly, the environment variables are ignored entirely.

python

from runtime_narrative import FailureDiagnosticsConfig

config = FailureDiagnosticsConfig(
    runtime_environment="production",
    failure_diagnostics="rich",
    allow_rich_in_production=True,
    app_roots=("/opt/myapp",),
    redact_extra=("internal_token", "db_url"),
)

with story("Pipeline", diagnostics_config=config):
    ...

Production behavior summary

bash

# Rich downgraded to lean silently in production
RUNTIME_NARRATIVE_ENV=production \
RUNTIME_NARRATIVE_FAILURE_DIAGNOSTICS=rich \
python myapp.py

# Rich permitted explicitly in production
RUNTIME_NARRATIVE_ENV=production \
RUNTIME_NARRATIVE_FAILURE_DIAGNOSTICS=rich \
RUNTIME_NARRATIVE_ALLOW_RICH_IN_PRODUCTION=1 \
python myapp.py

Next step

Read the Event Reference for the full field list of every event these variables influence, especially the diagnostics fields on FailureOccurred.