Configuration Reference

Versions, Labels, and Rollouts

VariableConfig — Full configuration for a variable:

Field	Description
`name`	Variable name (must match the name in `logfire.var()`)
`labels`	Dict of label name to `LabeledValue` or `LabelRef` objects
`latest_version`	`LatestVersion` with the most recent version’s number and value
`rollout`	Default `Rollout` specifying label weights
`overrides`	List of `RolloutOverride` for conditional targeting
`json_schema`	JSON Schema for validation (optional)
`description`	Human-readable description (optional)
`aliases`	Alternative names that resolve to this variable (optional, for migrations)
`example`	JSON-serialized example value, used as template in UI (optional)

LabeledValue — A label with an inline serialized value:

Field	Description
`version`	The version number this label points to
`serialized_value`	JSON-serialized value for this version

LabelRef — A label that references another label, 'latest', or 'code_default':

Field	Description
`version`	The version number this label points to (optional, can be `None` for label-to-label refs or `code_default`)
`ref`	Reference target: another label name, `'latest'`, or `'code_default'`

Use LabeledValue when the label has its own inline value. Use LabelRef when the label should follow a reference:

Another label name: Keeps two labels in sync — when the target label is moved, this label follows automatically. Useful when you want e.g. staging to always match production.
'latest': Always resolves to the most recently created version. This avoids duplicating large values when multiple labels point to the same version.
'code_default': Resolves to None, causing the SDK to fall back to the default value defined in code. Useful for disabling remote config for a specific label without removing it.

LatestVersion — The most recent version of a variable:

Field	Description
`version`	The version number
`serialized_value`	JSON-serialized value

Rollout — Label selection weights:

Field	Description
`labels`	Dict of label name to weight (0.0–1.0). Weights should sum to 1.0 or less.

If the labels dict is empty, all traffic uses the code default (the default value passed to logfire.var()). If label weights sum to less than 1.0, the remaining percentage uses the code default.

VariableTypeConfig

VariableTypeConfig — Configuration for a reusable type definition:

Field	Description
`name`	Unique name identifying this type
`json_schema`	JSON Schema describing the type structure
`description`	Human-readable description (optional)
`source_hint`	Hint about where this type is defined in code, e.g., `'myapp.config.FeatureConfig'` (optional)

Condition Types

Overrides use conditions to match against attributes:

Condition	Description
`ValueEquals`	Attribute equals a specific value
`ValueDoesNotEqual`	Attribute does not equal a specific value
`ValueIsIn`	Attribute is in a list of values
`ValueIsNotIn`	Attribute is not in a list of values
`ValueMatchesRegex`	Attribute matches a regex pattern
`ValueDoesNotMatchRegex`	Attribute does not match a regex pattern
`KeyIsPresent`	Attribute key exists
`KeyIsNotPresent`	Attribute key does not exist

Override Example

from logfire.variables.config import (
    KeyIsPresent,
    Rollout,
    RolloutOverride,
    ValueEquals,
    ValueIsIn,
)

overrides = [
    # Beta users in US/UK get the experimental label
    RolloutOverride(
        conditions=[
            ValueEquals(attribute='is_beta', value=True),
            ValueIsIn(attribute='country', values=['US', 'UK']),
        ],
        rollout=Rollout(labels={'experimental': 1.0}),
    ),
    # Anyone with a custom config attribute gets the custom label
    RolloutOverride(
        conditions=[KeyIsPresent(attribute='custom_config')],
        rollout=Rollout(labels={'custom': 1.0}),
    ),
]

Conditions within an override are AND-ed together. Overrides are evaluated in order; the first matching override’s rollout is used.

Advanced Usage

Contextual Overrides

Use variable.override() to temporarily override a variable’s value within a context. This is useful for testing:

def test_premium_config_handling():
    """Test that premium configuration works correctly."""
    premium_config = AgentConfig(
        instructions='Premium instructions...',
        model='openai:gpt-4o',
        temperature=0.3,
        max_tokens=1000,
    )

    with agent_config.override(premium_config):
        # Inside this context, agent_config.get() returns premium_config
        with agent_config.get() as config:
            assert config.value.model == 'openai:gpt-4o'

    # Back to normal after context exits

Dynamic Override Functions

Override with a function that computes the value based on context:

from collections.abc import Mapping
from typing import Any


def get_config_for_context(
    targeting_key: str | None, attributes: Mapping[str, Any] | None
) -> AgentConfig:
    """Compute configuration based on context."""
    if attributes and attributes.get('mode') == 'creative':
        return AgentConfig(
            instructions='Be creative and expressive...',
            model='openai:gpt-4o',
            temperature=1.0,
            max_tokens=1000,
        )
    return AgentConfig(
        instructions='Be precise and factual...',
        model='openai:gpt-4o-mini',
        temperature=0.2,
        max_tokens=500,
    )


with agent_config.override(get_config_for_context):
    # Configuration will be computed based on the attributes passed to get()
    with agent_config.get(attributes={'mode': 'creative'}) as config:
        assert config.value.temperature == 1.0

Refreshing Variables

Variables are automatically refreshed in the background when using the remote provider. You can also manually trigger a refresh:

# Synchronous refresh
agent_config.refresh_sync(force=True)

# Async refresh
await agent_config.refresh(force=True)

The force=True parameter bypasses the polling interval check and fetches the latest configuration immediately.

Migrating Variable Names

Variable names serve as the identifier used to reference the variable in your code. You can rename a variable in the UI or API, but any deployed code still using the old name will fall back to its code default. For zero-downtime migrations, use aliases.

Aliases allow a variable to be found by alternative names. When your code requests a variable by name, if that name isn’t found directly, the system checks if it matches any alias of an existing variable and returns that variable’s value instead.

Migration workflow:

Create the new variable with your desired name and copy the configuration (versions, labels, rollouts, overrides) from the old variable
Add the old name as an alias on the new variable
Update your code to use the new variable name
Deploy gradually: Applications using the old name will still work because the alias resolves to the new variable
Delete the old variable once all code has been updated and deployed
Remove the alias (optional) once you’re confident no code uses the old name

Example:

Suppose you have a variable named agent_config and want to rename it to support_agent_config:

Create support_agent_config with the same versions, labels, and rollout configuration
Add agent_config as an alias on support_agent_config
Old code using logfire.var(name='agent_config', ...) continues to work
Update your code to use name='support_agent_config'
After deployment, delete the old agent_config variable
Optionally remove agent_config from the aliases list

This approach ensures zero-downtime migrations. Existing deployed applications continue to receive the correct configuration while you update and redeploy.

In the UI:

You can manage aliases in the Aliases section of the Settings tab on the variable detail page. Add the old variable name(s) that should resolve to this variable.

In code (local config):

from logfire.variables.config import VariableConfig, VariablesConfig

config = VariablesConfig(
    variables={
        'support_agent_config': VariableConfig(
            name='support_agent_config',
            labels={...},
            latest_version=LatestVersion(...),
            rollout=Rollout(labels={...}),
            overrides=[],
            # Old name resolves to this variable
            aliases=['agent_config'],
        ),
    }
)