Connection configuration
Choose endpoints, tenant routing, timeouts and transport options.
Use one configuration per backend. PrometheusConfig uses standard API paths; VMSingleConfig and VMClusterConfig supply the VictoriaMetrics deployment paths. The client resolves endpoint suffixes.
from metricraft import PrometheusConfig, HttpClientOptions
config = PrometheusConfig(
"http://localhost:9090",
default_step="30s",
http_options=HttpClientOptions(timeout=(3, 20)),
)
config.validate()Put timeouts inside http_options; top-level timeout kwargs are rejected. Configuration objects can be updated. HttpClientOptions is a frozen container with copied dictionaries, not a recursively immutable object. For optional registry helpers, see models and shared types.
HTTP transport injection is typed with public sync/async Protocols and factory contracts. See replace the HTTP transport for adapter signatures, factory arguments and cleanup ownership.
Methods and parameters
PrometheusConfig
PrometheusConfig()Create connection settings for this backend. Configuration objects are mutable; immutable expression guarantees do not apply to configuration.
PrometheusConfig(url: str, default_step: str='1m', *, http_options: Optional[HttpClientOptions]=None, **kwargs)
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
urlstrRequired | Nonempty backend base URL, e.g. 'http://localhost:9090'. Do not append /api/v1/query; endpoint paths are added by the client. |
default_stepstrDefault: '1m' | Default range-query evaluation interval, e.g. '1m'. Use a positive backend duration; syntax is ultimately checked by the backend. |
http_optionsHttpClientOptions | Mapping | NoneDefault: None | Transport settings; None uses backend configuration defaults (30-second transport timeout). |
**kwargskeyword argumentsVariadic | Additional connection settings. A top-level timeout is rejected: put timeout inside http_options. |
Returns PrometheusConfig
db_typeReturn this backend's DBType discriminator.
PrometheusConfig.db_type
Configuration and transport validation are separate from query validation.
No parameters.
Returns DBType
get_connection_info()Return resolved backend connection settings and HTTP options.
PrometheusConfig.get_connection_info() -> Dict[str, Any]
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
get_insert_url_base()Return the insertion base URL. PrometheusConfig raises NotImplementedError because it has no VictoriaMetrics import endpoint.
PrometheusConfig.get_insert_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
get_query_url_base()Return the query base URL with any deployment/tenant prefix; the client adds the endpoint.
PrometheusConfig.get_query_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
http_optionsReturn the stored HttpClientOptions object.
PrometheusConfig.http_options
Configuration and transport validation are separate from query validation.
No parameters.
Returns HttpClientOptions
http_options_dictExport HTTP options as a dictionary for transport setup.
PrometheusConfig.http_options_dict
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
set_http_options()Replace HTTP options on this configuration object.
PrometheusConfig.set_http_options(options: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
optionsHttpClientOptions | Mapping | NoneRequired | Replacement HTTP settings; mutates this configuration object, not query expressions. |
Returns None
update_http_options()Merge HTTP options into this configuration, retaining unspecified settings.
PrometheusConfig.update_http_options(overrides: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
overridesHttpClientOptions | Mapping | NoneRequired | Settings to merge with existing HTTP options. Headers and extras merge by key; other supplied fields override. |
Returns None
validate()Check required endpoints and settings; raise ValueError for invalid configuration.
PrometheusConfig.validate() -> None
Configuration and transport validation are separate from query validation.
No parameters.
Returns None
VMSingleConfig
VMSingleConfig()Create connection settings for this backend. Configuration objects are mutable; immutable expression guarantees do not apply to configuration.
VMSingleConfig(url: str, default_step: str='1m', *, http_options: Optional[HttpClientOptions]=None, **kwargs)
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
urlstrRequired | Nonempty backend base URL, e.g. 'http://localhost:9090'. Do not append /api/v1/query; endpoint paths are added by the client. |
default_stepstrDefault: '1m' | Default range-query evaluation interval, e.g. '1m'. Use a positive backend duration; syntax is ultimately checked by the backend. |
http_optionsHttpClientOptions | Mapping | NoneDefault: None | Transport settings; None uses backend configuration defaults (30-second transport timeout). |
**kwargskeyword argumentsVariadic | Additional connection settings. A top-level timeout is rejected: put timeout inside http_options. |
Returns VMSingleConfig
db_typeReturn this backend's DBType discriminator.
VMSingleConfig.db_type
Configuration and transport validation are separate from query validation.
No parameters.
Returns DBType
get_connection_info()Return resolved backend connection settings and HTTP options.
VMSingleConfig.get_connection_info() -> Dict[str, Any]
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
get_insert_url_base()Return the insertion base URL. PrometheusConfig raises NotImplementedError because it has no VictoriaMetrics import endpoint.
VMSingleConfig.get_insert_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
get_query_url_base()Return the query base URL with any deployment/tenant prefix; the client adds the endpoint.
VMSingleConfig.get_query_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
http_optionsReturn the stored HttpClientOptions object.
VMSingleConfig.http_options
Configuration and transport validation are separate from query validation.
No parameters.
Returns HttpClientOptions
http_options_dictExport HTTP options as a dictionary for transport setup.
VMSingleConfig.http_options_dict
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
set_http_options()Replace HTTP options on this configuration object.
VMSingleConfig.set_http_options(options: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
optionsHttpClientOptions | Mapping | NoneRequired | Replacement HTTP settings; mutates this configuration object, not query expressions. |
Returns None
update_http_options()Merge HTTP options into this configuration, retaining unspecified settings.
VMSingleConfig.update_http_options(overrides: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
overridesHttpClientOptions | Mapping | NoneRequired | Settings to merge with existing HTTP options. Headers and extras merge by key; other supplied fields override. |
Returns None
validate()Check required endpoints and settings; raise ValueError for invalid configuration.
VMSingleConfig.validate() -> None
Configuration and transport validation are separate from query validation.
No parameters.
Returns None
VMClusterConfig
VMClusterConfig()Create connection settings for this backend. Configuration objects are mutable; immutable expression guarantees do not apply to configuration.
VMClusterConfig(vminsert_url: str, vmselect_url: str, vmstorage_url: str, account_id: int=DEFAULT_ACCOUNT_ID, default_step: str='1m', *, http_options: Optional[HttpClientOptions]=None, **kwargs)
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
vminsert_urlstrRequired | VictoriaMetrics vminsert base URL, e.g. 'http://localhost:8480'; tenant insertion paths are added automatically. |
vmselect_urlstrRequired | VictoriaMetrics vmselect base URL, e.g. 'http://localhost:8481'; tenant query paths are added automatically. |
vmstorage_urlstrRequired | VictoriaMetrics vmstorage base URL, e.g. 'http://localhost:8482'. |
account_idintDefault: DEFAULT_ACCOUNT_ID | Nonnegative integer cluster tenant ID (default 0). |
default_stepstrDefault: '1m' | Default range-query evaluation interval, e.g. '1m'. Use a positive backend duration; syntax is ultimately checked by the backend. |
http_optionsHttpClientOptions | Mapping | NoneDefault: None | Transport settings; None uses backend configuration defaults (30-second transport timeout). |
**kwargskeyword argumentsVariadic | Additional connection settings. A top-level timeout is rejected: put timeout inside http_options. |
Returns VMClusterConfig
db_typeReturn this backend's DBType discriminator.
VMClusterConfig.db_type
Configuration and transport validation are separate from query validation.
No parameters.
Returns DBType
get_connection_info()Return resolved backend connection settings and HTTP options.
VMClusterConfig.get_connection_info() -> Dict[str, Any]
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
get_insert_url_base()Return the insertion base URL. PrometheusConfig raises NotImplementedError because it has no VictoriaMetrics import endpoint.
VMClusterConfig.get_insert_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
get_query_url_base()Return the query base URL with any deployment/tenant prefix; the client adds the endpoint.
VMClusterConfig.get_query_url_base() -> str
Configuration and transport validation are separate from query validation.
No parameters.
Returns str
http_optionsReturn the stored HttpClientOptions object.
VMClusterConfig.http_options
Configuration and transport validation are separate from query validation.
No parameters.
Returns HttpClientOptions
http_options_dictExport HTTP options as a dictionary for transport setup.
VMClusterConfig.http_options_dict
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]
set_http_options()Replace HTTP options on this configuration object.
VMClusterConfig.set_http_options(options: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
optionsHttpClientOptions | Mapping | NoneRequired | Replacement HTTP settings; mutates this configuration object, not query expressions. |
Returns None
update_http_options()Merge HTTP options into this configuration, retaining unspecified settings.
VMClusterConfig.update_http_options(overrides: Optional[HttpClientOptions]) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
overridesHttpClientOptions | Mapping | NoneRequired | Settings to merge with existing HTTP options. Headers and extras merge by key; other supplied fields override. |
Returns None
validate()Check required endpoints and settings; raise ValueError for invalid configuration.
VMClusterConfig.validate() -> None
Configuration and transport validation are separate from query validation.
No parameters.
Returns None
HttpClientOptions
HttpClientOptions()Create frozen transport options. Header/extras dictionaries are copied; freezing does not recursively freeze their contents.
HttpClientOptions(timeout: Optional[RawTimeout]=None, default_headers: Optional[HeadersMapping]=None, prepare_request: Optional[Callable[..., Any]]=None, opener: Optional[Callable[..., Any]]=None, client: Optional[SyncHTTPTransport]=None, async_client: Optional[AsyncHTTPTransport]=None, client_factory: Optional[SyncHTTPTransportFactory]=None, async_client_factory: Optional[AsyncHTTPTransportFactory]=None, max_workers: Optional[int]=None, executor: Optional[Any]=None, extras: Optional[Mapping[str, Any]]=None) -> None
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
timeoutnumber | tuple[number, number] | NoneDefault: None | Positive connect/read timeouts in seconds; a scalar applies to both. None leaves timeout unspecified for the owning configuration/transport. |
default_headersMapping[str, str]Default: None | Default HTTP request headers; names and values are normalized into a copied dictionary. |
prepare_requestCallable | NoneDefault: None | Hook for preparing the transport request before sending; must follow the selected transport's request contract. |
openerCallable | NoneDefault: None | Optional urllib-compatible synchronous request opener. |
clientSyncHTTPTransport | NoneDefault: None | Injected sync adapter with get/post returning decoded JSON objects; the client owns cleanup. |
async_clientAsyncHTTPTransport | NoneDefault: None | Injected async adapter with awaitable get/post returning decoded JSON objects; use aclose for async cleanup. |
client_factorySyncHTTPTransportFactory | NoneDefault: None | Called with keyword arguments http_options and connection_info when client is absent. |
async_client_factoryAsyncHTTPTransportFactory | NoneDefault: None | Regular factory called with http_options, connection_info and sync_client when async_client is absent. |
max_workersint | NoneDefault: None | Positive worker count for the async fallback executor; None uses the executor default. |
executorExecutor | NoneDefault: None | Optional executor used by the async fallback; externally supplied executors remain caller-owned. |
extrasMapping[str, Any]Default: None | Additional transport-specific options copied into the configuration; their meaning belongs to the selected transport. |
Returns None
ensure()Normalize None, a mapping or existing options into HttpClientOptions.
HttpClientOptions.ensure(value: Optional[Union['HttpClientOptions', Mapping[str, Any]]]) -> 'HttpClientOptions'
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
valueHttpClientOptions | Mapping[str, Any] | NoneRequired | Return an existing options object, convert a mapping, or use an empty options object for None. |
Returns 'HttpClientOptions'
from_mapping()Create HTTP options from a mapping, normalize aliases and retain unknown transport keys in extras.
HttpClientOptions.from_mapping(data: Mapping[str, Any]) -> 'HttpClientOptions'
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
dataMapping[str, Any]Required | HTTP option mapping. The headers key aliases default_headers; unrecognized keys are retained in extras. |
Returns 'HttpClientOptions'
merge()Return new HTTP options with overrides. Headers and extras merge by key; non-None fields replace existing values.
HttpClientOptions.merge(overrides: Optional[Union['HttpClientOptions', Mapping[str, Any]]]) -> 'HttpClientOptions'
Configuration and transport validation are separate from query validation.
| Parameter / type | Meaning and accepted values |
|---|---|
overridesHttpClientOptions | Mapping | NoneRequired | Settings to merge with existing HTTP options. Headers and extras merge by key; other supplied fields override. |
Returns 'HttpClientOptions'
to_dict()Export configured HTTP settings and extras as a dictionary.
HttpClientOptions.to_dict() -> Dict[str, Any]
Configuration and transport validation are separate from query validation.
No parameters.
Returns Dict[str, Any]