roboto.domain.metrics.record

Module Contents

class roboto.domain.metrics.record.AggregateMetricRecord(/, **data)

Bases: pydantic.BaseModel

!!! abstract “Usage Documentation”

[Models](../concepts/models.md)

A base class for creating Pydantic models.

Parameters:

data (Any)

__class_vars__

The names of the class variables defined on the model.

__private_attributes__

Metadata about the private attributes of the model.

__signature__

The synthesized __init__ [Signature][inspect.Signature] of the model.

__pydantic_complete__

Whether model building is completed, or if there are still undefined fields.

__pydantic_core_schema__

The core schema of the model.

__pydantic_custom_init__

Whether the model has a custom __init__ function.

__pydantic_decorators__

Metadata containing the decorators defined on the model. This replaces Model.__validators__ and Model.__root_validators__ from Pydantic V1.

__pydantic_generic_metadata__

A dictionary containing metadata about generic Pydantic models. The origin and args items map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and the parameter item maps to the __parameter__ attribute of generic classes.

__pydantic_parent_namespace__

Parent namespace of the model, used for automatic rebuilding of models.

__pydantic_post_init__

The name of the post-init method for the model, if defined.

__pydantic_root_model__

Whether the model is a [RootModel][pydantic.root_model.RootModel].

__pydantic_serializer__

The pydantic-core SchemaSerializer used to dump instances of the model.

__pydantic_validator__

The pydantic-core SchemaValidator used to validate instances of the model.

__pydantic_fields__

A dictionary of field names and their corresponding [FieldInfo][pydantic.fields.FieldInfo] objects.

__pydantic_computed_fields__

A dictionary of computed field names and their corresponding [ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects.

__pydantic_extra__

A dictionary containing extra values, if [extra][pydantic.config.ConfigDict.extra] is set to ‘allow’.

__pydantic_fields_set__

The names of fields explicitly set during instantiation.

__pydantic_private__

Values of private attributes set on the model instance.

end_time: int

midnight in the request’s time_zone on the next period’s first day. A period in which that zone’s clocks change is longer or shorter by the size of the change, so a daily bucket can span 23 or 25 hours.

Type:

Exclusive end of this period bucket, in Unix-epoch nanoseconds

metric_id: str

Identifier of the aggregated metric definition.

name: str

Name of the aggregated metric.

period: AggregationPeriod

Calendar bucket size used for this aggregation.

start_time: int

midnight in the request’s time_zone on the period’s first day.

Type:

Inclusive start of this period bucket, in Unix-epoch nanoseconds

total: int

Number of raw observations that contributed to this bucket.

class roboto.domain.metrics.record.AggregateMetricsRequest(/, **data)

Bases: pydantic.BaseModel

Request payload for a numeric metric aggregation.

Parameters:

data (Any)

aggregation: NumericAggregation

Aggregation function to apply to the values in each bucket.

condition: roboto.query.ConditionType | None = None

Condition, or nested group of conditions, narrowing which data points are aggregated.

Applied to individual data points rather than to bucket results, so it changes each bucket’s value and total. A period whose data points are all filtered out yields no bucket at all, so a filtered aggregation can return fewer buckets than an unfiltered one over the same window. See condition for the accepted fields and the treatment of data points published without a device.

end_time_ns: int

Exclusive end of the aggregation window, in Unix-epoch nanoseconds (UTC). Built from aggregate()’s end_time parameter the same way.

group_by: str | None = None

one NumericAggregateMetricRecord per (period, distinct value) pair, each carrying the value it aggregated under group_key.

None aggregates every matching data point of a period into one bucket. Accepts device.device_id and String, Enum, or Boolean custom fields on sessions and devices (session.custom.<name>, device.custom.<name>); every other field of the vocabulary condition accepts is rejected, since a group key must be single-valued and low-cardinality to be a series. Data points carrying no value for the field are grouped under a null group_key rather than dropped. At most MAX_METRIC_GROUPS named values come back — those with the most sessions in the requested window — plus the null group; the response reports the full count in NumericAggregateMetricsResponse.total_groups.

Type:

Field to split the aggregation by, in addition to the period bucket

include_device_ids: list[str] | roboto.sentinels.NotSetType | None

Filter to observations from specific device IDs, None for null device_id only.

include_invocation_ids: list[str] | roboto.sentinels.NotSetType | None

Filter to observations from specific invocation IDs, None for null invocation_id only.

include_session_ids: list[str] | roboto.sentinels.NotSetType

Filter to observations for specific session IDs. None is not a valid value: metrics.session_id is non-nullable, so there is no “null session” subset to filter on. Omit (leave as NotSet) for no filter, or pass a list of IDs.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

Name of the metric to aggregate.

period: AggregationPeriod

Calendar bucket size to group observations by.

start_time_ns: int

Inclusive start of the aggregation window, in Unix-epoch nanoseconds (UTC). Built by aggregate() from its start_time parameter via to_epoch_nanoseconds().

time_filter: MetricTimeFilter

Whether to filter by session start time or end time.

time_zone: str = 'UTC'

IANA name of the time zone in which each period starts at midnight, such as "America/Los_Angeles". The periods, and the window when widen_to_whole_periods widens it, are cut in this zone, and a day on which the zone’s clocks change is longer or shorter than 24 hours. A name not in the IANA time zone database raises RobotoIllegalArgumentException, as do CET, EET, MET, and WET, which the service would read as fixed UTC offsets without daylight saving time; name such a zone by area and location instead, such as "Europe/Paris" for CET.

week_start: DayOfWeek

The day each week starts on when period is AggregationPeriod.Weekly. Other periods ignore it.

widen_to_whole_periods: bool = True

Whether to widen the window to whole periods. When true, the service moves start_time_ns back to the start of its period and end_time_ns forward to the end of its period, so the first and last buckets aggregate every data point of their period, including those of sessions outside the requested window. When false, a bucket aggregates only the data points inside [start_time_ns, end_time_ns), the same data points a QueryMetricsRequest with the same window, time_filter and filters returns, so the first and last buckets can hold part of their period. Either way, each bucket’s start_time and end_time are the bounds of its whole period.

class roboto.domain.metrics.record.AggregationPeriod

Bases: roboto.compat.StrEnum

Calendar bucket size used when grouping metric observations.

Each period starts at midnight in AggregateMetricsRequest.time_zone, and each week starts on AggregateMetricsRequest.week_start.

Daily = 'daily'

One bucket per calendar day.

Monthly = 'monthly'

One bucket per calendar month.

Quarterly = 'quarterly'

One bucket per calendar quarter (three months).

Weekly = 'weekly'

One bucket per calendar week.

Yearly = 'yearly'

One bucket per calendar year.

class roboto.domain.metrics.record.CreateMetricDefinitionRequest(/, **data)

Bases: pydantic.BaseModel

Request payload to create a metric definition.

Parameters:

data (Any)

description: str | None = None

Human-readable description of what the metric measures.

name: str

Unique metric name.

unit: MetricUnit | None = None

Unit of measure for values recorded under this metric, e.g. "%", "ms". Capped at 63 characters. None means unitless.

class roboto.domain.metrics.record.DayOfWeek

Bases: roboto.compat.StrEnum

A day of the week, such as the day an aggregation’s weeks start on.

Friday = 'friday'

Monday = 'monday'

Saturday = 'saturday'

Sunday = 'sunday'

Thursday = 'thursday'

Tuesday = 'tuesday'

Wednesday = 'wednesday'

roboto.domain.metrics.record.MAX_METRIC_GROUPS: int = 100

The most named groups a grouped metrics read returns.

A read with group_by keeps the named values with the most sessions (data points) in the requested window, ties broken alphabetically by value, and drops every data point of the rest. The null group (data points with no value for the field) is never dropped and does not count toward the cap. The ranking does not depend on the aggregation, the period, or which page of a raw query is read, so the same window always keeps the same groups. Responses report the full count in total_groups and whether anything was dropped in groups_truncated.

roboto.domain.metrics.record.MAX_METRIC_LIST_RESULTS: int = 10000

Upper bound on the page size accepted by metric query and list calls.

query() auto-paginates with this value as the default page size, so total result-set size is unbounded. Callers can request smaller pages by setting max_results.

get_by_session() does not paginate and is still capped at this many rows; sessions with more data points should use the paginated query() instead.

class roboto.domain.metrics.record.MetricDefinitionRecord(/, **data)

Bases: pydantic.BaseModel

A wire-transmissible representation of a metric definition.

Parameters:

data (Any)

created: datetime.datetime

Timestamp when this metric definition was created.

created_by: str

User or service account that created this metric definition.

description: str | None = None

Human-readable description of what the metric measures.

metric_id: str

Unique identifier for this metric definition.

modified: datetime.datetime

Timestamp when this metric definition was last modified.

modified_by: str

User or service account that last modified this metric definition.

name: str

Unique name for this metric.

org_id: str

Organization that owns this metric definition.

unit: str | None = None

Unit of measure for every value recorded under this metric, e.g. "%", "ms", "m/s". Free-form and unvalidated; None means unitless.

class roboto.domain.metrics.record.MetricEntry(/, **data)

Bases: pydantic.BaseModel

A single name+value pair within a bulk metric publish.

Parameters:

data (Any)

name: str

Name of the metric definition to record a value for. If the definition does not exist, it is auto-created.

value: float

Observed numeric value.

class roboto.domain.metrics.record.MetricQueryPage

Bases: roboto.http.response.PaginatedList[MetricRecord]

One page of raw metric data points, from query().

Carries the same group summary on every page of one read.

groups_truncated: bool = False

Whether total_groups exceeds MAX_METRIC_GROUPS, so data points under the named values with the fewest sessions were dropped from every page.

total_groups: int | None = None

How many distinct named values of QueryMetricsRequest.group_by have data in the queried window, counting none for data points with no value. None on an ungrouped query.

class roboto.domain.metrics.record.MetricRecord(/, **data)

Bases: pydantic.BaseModel

A wire-transmissible representation of a metric data point.

Parameters:

data (Any)

device_id: str | None = None

Device that produced the data.

group_key: str | None = None

Value of the field named by QueryMetricsRequest.group_by that this data point carries, rendered as text whatever the field’s type. None on every data point of an ungrouped query, and on a data point that carries no value for that field — one published without a device, or whose session or device has never been given a value for the custom field. Mirrors NumericAggregateMetricRecord.group_key, which splits buckets the same way.

invocation_id: str | None = None

Action invocation that produced this data point, if any.

max_timestamp_ns: int | None = None

Latest time covered by the data point’s session, in Unix-epoch nanoseconds: that session’s max_timestamp_ns. None in the same cases as min_timestamp_ns.

metric_id: str

Identifier of the metric definition this data point belongs to.

min_timestamp_ns: int | None = None

Earliest time covered by the data point’s session, in Unix-epoch nanoseconds: that session’s min_timestamp_ns. None while the session has no start or end time, because none of its files gives it timestamped data (for example, before it holds any file).

name: str

Human-readable name of the metric definition this data point belongs to. Resolved server-side from the parent MetricDefinitionRecord so callers do not need a second lookup to display the metric name alongside the value.

org_id: str

Organization that owns this metric data point.

published: datetime.datetime

Timestamp when this data point was published to the platform.

published_by: str

User or service account that published this data point.

session_end_time_ns: int | None = None

The time a time_filter of MetricTimeFilter.EndTime places this data point at, in Unix-epoch nanoseconds: the session’s max_timestamp_ns, or the time the session was created while it has no start or end time. Used as session_start_time_ns is. None only on a record from a service older than this field.

session_id: str

Session this metric is associated with.

session_start_time_ns: int | None = None

The time a time_filter of MetricTimeFilter.StartTime places this data point at, in Unix-epoch nanoseconds: the session’s min_timestamp_ns, or the time the session was created while it has no start or end time. A query or aggregation window holds the data point when it holds this time, and an aggregation counts it in the period that holds this time. None only on a record from a service older than this field.

unit: str | None = None

Unit of measure for value. Resolved server-side from the parent MetricDefinitionRecord, like name, so callers can label a value without a second lookup. None means unitless.

value: float

Observed numeric value.

class roboto.domain.metrics.record.MetricTimeFilter

Bases: roboto.compat.StrEnum

Enum where members are also (and must be) strings

EndTime = 'end_time'

StartTime = 'start_time'

roboto.domain.metrics.record.MetricUnit

class roboto.domain.metrics.record.NumericAggregateMetricRecord(/, **data)

Bases: AggregateMetricRecord

A wire-transmissible representation of one period bucket in a numeric metric aggregation.

Parameters:

data (Any)

aggregation: NumericAggregation

Aggregation function that was applied to produce this record.

group_key: str | None = None

Value of the field named by AggregateMetricsRequest.group_by that this bucket’s data points share, rendered as text whatever the field’s type. None on every bucket of an ungrouped aggregation, and on the bucket collecting the grouped data points that carry no value for that field — a data point published without a device, or a session or device that has never been given a value for the custom field.

unit: str | None = None

Unit of measure for value, resolved from the aggregated metric’s definition alongside name. None means unitless.

value: float

Aggregated result for this bucket.

class roboto.domain.metrics.record.NumericAggregateMetricsResponse(/, **data)

Bases: pydantic.BaseModel

Response payload for a numeric metric aggregation request.

Parameters:

data (Any)

aggregation: NumericAggregation

Aggregation function that was applied.

groups_truncated: bool = False

Whether total_groups exceeds MAX_METRIC_GROUPS, so only the named groups with the most sessions in the window (plus the null group) came back. See AggregateMetricsRequest.group_by.

records: list[NumericAggregateMetricRecord]

Period buckets returned by the aggregation, sorted by start_time ascending.

total_groups: int | None = None

How many distinct named values of AggregateMetricsRequest.group_by have data in the returned periods, counting none for data points with no value. When AggregateMetricsRequest.widen_to_whole_periods is true, the periods can reach past the requested window to whole-period bounds, so this includes a value whose data falls only in that margin. None on an ungrouped aggregation.

class roboto.domain.metrics.record.NumericAggregation

Bases: roboto.compat.StrEnum

Aggregation function applied to numeric metric values within each period bucket.

Count = 'count'

Count of observations in the bucket.

Max = 'max'

Maximum value observed in the bucket.

Mean = 'mean'

Arithmetic mean of all values in the bucket.

Min = 'min'

Minimum value observed in the bucket.

Sum = 'sum'

Sum of all values in the bucket.

class roboto.domain.metrics.record.PublishMetricsRequest(/, **data)

Bases: pydantic.BaseModel

Request payload to insert multiple metric data points in a single call.

Parameters:

data (Any)

device_id: roboto.sentinels.NotSetType | str | None

Device that produced the data. When absent (NotSet), the server infers the device from the session’s attached devices: the request succeeds if exactly one device is attached and is rejected otherwise. Pass an explicit device ID or None to skip inference.

metrics: list[MetricEntry]

Metric data points to insert.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

session_id: str

Session all metrics in this batch will be attached to.

class roboto.domain.metrics.record.QueryMetricsRequest(/, **data)

Bases: pydantic.BaseModel

Request payload to query raw metric data points.

Exactly one of name and names selects the metrics to read.

Parameters:

data (Any)

condition: roboto.query.ConditionType | None = None

Condition, or nested group of conditions, narrowing which data points are returned.

Every field must be prefixed with the entity it filters on, singular or plural; a bare field name such as name is rejected. The available fields are:

• session.<field>: session_id (alias id), name, min_timestamp_ns (alias start_time), max_timestamp_ns (alias end_time), duration, created, created_by, modified, modified_by, tags. The two timestamp bounds accept anything to_epoch_nanoseconds() converts; duration takes an integer count of nanoseconds.

• device.<field>: device_id (alias id), tags, created, created_by, modified, modified_by, metadata (including dotted paths beneath it). Reads the device that published the data point, not the devices attached to its session.

• session.custom.<name> / device.custom.<name> / collection.custom.<name>: a custom field in the Ready state.

• collection.collection_id (alias collection.id): the data point’s session belongs to that collection. Equals and NotEquals only.

A session belongs to any number of collections, so a collection.* condition quantifies over that set: a data point matches when its session belongs to at least one collection satisfying the condition. A negated comparator (NotEquals, NotContains, NotLike) means the session belongs to no collection satisfying the positive form, so a session in no collection at all matches every negated collection condition. IsNull and NotExists likewise mean no collection the session belongs to carries a value for the field.

A data point published without a device matches a device.* condition only under IsNull and NotExists. Every other comparator asks what the device’s field holds, NotEquals, NotContains, and NotLike included, so a data point with no device, or a device carrying no value for the field, is excluded. Write device.<field> NotEquals x OR device.<field> IsNull to match both.

Any other field, a comparator the field’s type does not accept, a value the field cannot convert, or a Not group raises RobotoIllegalArgumentException.

descending: bool = False

Order data points from the largest sort_by value to the smallest, instead of smallest first.

With the default sort_by, this returns the most recent data points first.

end_time_ns: int | None = None

Exclusive end of the query window, in Unix-epoch nanoseconds (UTC). Built from query()’s end_time parameter the same way. Defaults to None (now).

group_by: str | None = None

Field whose value each returned data point should carry, under MetricRecord.group_key.

Unlike AggregateMetricsRequest.group_by, this does not add rows: a raw query already returns one data point per session, so there is nothing to split. It projects the field’s value onto each one, which is what lets a caller separate the points into a series per distinct value without resolving the field itself.

None leaves MetricRecord.group_key null on every data point. Accepts the same vocabulary the aggregation does — device.device_id and String, Enum, or Boolean custom fields on sessions and devices (session.custom.<name>, device.custom.<name>) — and rejects every other field of condition’s vocabulary with RobotoIllegalArgumentException. A data point carrying no value for the field gets a null group_key rather than being dropped.

Grouping can drop rows, though: at most MAX_METRIC_GROUPS named values are kept across every page, those with the most sessions in the queried window, and data points under the rest are dropped. Each MetricQueryPage reports the full count in total_groups and whether any were dropped in groups_truncated.

include_device_ids: list[str] | roboto.sentinels.NotSetType | None

Filter to observations from specific device IDs, None for null device_id only.

include_invocation_ids: list[str] | roboto.sentinels.NotSetType | None

Filter to observations from specific invocation IDs, None for null invocation_id only.

include_session_ids: list[str] | roboto.sentinels.NotSetType

Filter to observations for specific session IDs. None is not a valid value: metrics.session_id is non-nullable, so there is no “null session” subset to filter on. Omit (leave as NotSet) for no filter, or pass a list of IDs.

max_results: int

Maximum number of data points to return. Must be between 1 and MAX_METRIC_LIST_RESULTS (10,000).

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None = None

Name of the metric to query.

names: list[str] | None = None

names may change or be removed without notice.

Names of the metrics to read together as one paginated result: at least one, none repeated. Each returned MetricRecord carries its own name and metric_id, which tell the rows of different metrics apart. A list of one name reads and pages as name does.

Replay a page token only with the list of names it was issued under. A token issued under name or a one-name list is rejected with RobotoInvalidRequestException when replayed with two or more names, and a token issued under two or more names is rejected when replayed with one.

Type:

Experimental

sort_by: str | None = None

Field to order data points by, with session_id as a deterministic tiebreaker and, when names lists several metrics, metric_id after it.

One of time (the session time selected by time_filter), value, published, device_id, session_id, invocation_id, or group_key (the value of group_by, carried on MetricRecord.group_key, and accepted only when group_by is set); any other field is rejected with RobotoInvalidRequestException. Data points with no device_id, invocation_id or group key sort after every other value. Defaults to time.

start_time_ns: int | None = None

Inclusive start of the query window, in Unix-epoch nanoseconds (UTC). Built by query() from its start_time parameter via to_epoch_nanoseconds(). Defaults to None (the Unix epoch).

time_filter: MetricTimeFilter

Whether to filter by session start time or end time.

class roboto.domain.metrics.record.UpdateMetricDefinitionRequest(/, **data)

Bases: pydantic.BaseModel

Request payload to update a metric definition.

Parameters:

data (Any)

description: roboto.sentinels.NotSetType | str | None

New description, None to clear, or NotSet to leave unchanged.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

unit: roboto.sentinels.NotSetType | MetricUnit | None

New unit of measure (max 63 characters), None to clear, or NotSet to leave unchanged.