Telemetry names
Chronicle preserves existing kernel metric names and metadata by default (Telemetry:MetricNames=Legacy). Opt into Telemetry:MetricNames=Convention to publish metrics under cratis.chronicle.*, with UCUM units and shared attribute keys. The public .NET registry is the WellKnownTelemetryAttributes, WellKnownMetricNames, WellKnownSpanNames and WellKnownClientSpanNames classes in Cratis.Chronicle.Diagnostics. Client metrics will use cratis.chronicle.client.*; this change does not add client metrics.
Compatibility and migration
Section titled “Compatibility and migration”Choose the kernel’s metric naming mode independently of client Telemetry:SpanNames:
Telemetry:MetricNames |
Published instruments |
|---|---|
Legacy (default) |
Existing names, units, descriptions, and attribute keys only |
Convention (opt-in) |
Convention names, UCUM units, and shared attribute keys only |
Both (opt-in migration mode) |
Both precreated sets, with each measurement recorded once to each set |
Both is intended for comparing old and new dashboards during migration. It increases telemetry volume and series count. Do not sum both series: they represent the same measurements. Switch dashboard queries and alerts to the new names and dimensions together, then switch to Convention. Instrument selection happens once when a producer is constructed; recording does not translate names or dimension keys. Restart the kernel when changing the mode.
Convention is planned to become the default in the next major version, when legacy metric names and keys are planned for removal. Legacy span keys are also deprecated for removal in the next major version.
The retry-attempt counter is an exception: chronicle-observer-partition-retry-attempts remains at its original recording point, after delivery fencing succeeds. It has no convention counterpart and is published only in Legacy and Both modes. Use cratis.chronicle.observer.partition_failures to count failed handling attempts. If recording a fence throws, a failure is counted but a retry attempt is not.
Metric names below are raw OpenTelemetry names. Prometheus exporters typically replace dots with underscores and append _total to counters. Never include _total in the instrument name. Exporter translation settings can affect the final query spelling.
Kernel metrics
Section titled “Kernel metrics”Every convention suffix in this table has the prefix cratis.chronicle.. Legacy names are complete. Brace units count the named entity; s is seconds and 1 is dimensionless.
| Convention suffix | Unit | Legacy instrument |
|---|---|---|
observer.successful_observations |
{observation} |
chronicle-observer-successful-observations |
observer.partition_failures |
{failure} |
chronicle-observer-partitions-failed |
observer.partitions_quarantined |
{partition} |
chronicle-observer-partitions-quarantined |
observer.partition_quarantines_cleared |
{partition} |
chronicle-observer-partition-quarantines-cleared |
observer.quarantines |
{quarantine} |
chronicle-observer-quarantined |
observer.suspected_skipped_events |
{event} |
chronicle-observer-events-suspected-skipped |
observer.zero_work_catch_ups |
{catch_up} |
chronicle-observer-zero-work-catch-ups |
observer.claim_divergences |
{divergence} |
chronicle-observer-claim-divergences |
webhook.probes_scheduled |
{probe} |
chronicle-webhook-probe-scheduled |
webhook.probe_attempts |
{probe} |
chronicle-webhook-probe-attempts |
webhook.probe_failures |
{probe} |
chronicle-webhook-probe-failures |
webhook.probe_successes |
{probe} |
chronicle-webhook-probe-successes |
webhook.probe_resumes |
{probe} |
chronicle-webhook-probe-resumes |
webhook.probes_deferred |
{probe} |
chronicle-webhook-probe-deferred |
webhook.probes_skipped |
{probe} |
chronicle-webhook-probe-skipped |
webhook.probes_cancelled |
{probe} |
chronicle-webhook-probe-cancelled |
webhook.circuit_openings |
{opening} |
chronicle-webhook-circuit-opened |
webhook.circuit_rejections |
{delivery} |
chronicle-webhook-circuit-rejected |
event_sequence.appended_events |
{event} |
chronicle-event-sequences-appended-events |
event_sequence.duplicate_sequence_numbers |
{event} |
chronicle-event-sequences-duplicate-event-sequence-numbers |
event_sequence.append_failures |
{event} |
chronicle-event-sequences-failed-appended-events |
event_sequence.constraint_violations |
{violation} |
chronicle-event-sequences-constraint-violations |
event_sequence.unknown_append_outcomes |
{append} |
chronicle-event-sequences-append-outcomes-unknown |
constraint_index.update_failures |
{failure} |
chronicle-event-sequences-constraint-index-update-failures |
constraint_index.settled_errors |
{event} |
chronicle-event-sequences-constraint-index-settled-errors |
constraint_index.poison_events |
{event} |
chronicle-event-sequences-constraint-index-poison-events |
constraint_index.repairs |
{repair} |
chronicle-event-sequences-constraint-index-repairs |
constraint_index.refusals |
{append} |
chronicle-event-sequences-constraint-index-refusals |
constraint_index.lag |
{event} |
chronicle-event-sequences-constraint-index-lag |
appended_events_queue.enqueued_events |
{event} |
chronicle-appended-events-queue-events-enqueued |
appended_events_queue.handled_events |
{event} |
chronicle-appended-events-queue-events-handled |
appended_events_queue.handling_failures |
{failure} |
chronicle-appended-events-queue-events-handling-failures |
appended_events_queue.spilled_events |
{event} |
chronicle-appended-events-queue-events-spilled-to-catchup |
appended_events_queue.catch_up_trigger_budget_exceeded |
{trigger} |
chronicle-appended-events-queue-catchup-trigger-budget-exceeded |
appended_events_queue.suspected_undelivered_events |
{event} |
chronicle-appended-events-queue-suspected-undelivered-events |
appended_events_queue.observer_spills |
{spill} |
chronicle-appended-events-queue-observers-spilled-to-catchup |
alert.failed_transitions |
{transition} |
chronicle-alert-transitions-failed |
alert.open_incidents |
{incident} |
chronicle-alerts-open-incidents |
alert.open_incidents_available |
1 |
chronicle-alerts-open-incidents-available |
abandoned_delivery.late_results |
{result} |
abandoned-delivery-late-results |
abandoned_delivery.hold_expirations |
{delivery} |
abandoned-delivery-hold-expirations |
abandoned_delivery.fence_duration |
s |
abandoned-delivery-fence-duration |
connected_client.count |
{client} |
chronicle-connected-clients |
sql.schema_lock.wait_duration |
s |
chronicle-sql-schema-lock-wait |
sql.live_query.poll_failures |
{poll} |
chronicle-sql-live-query-poll-failures |
sql.upsert.recovered_collisions |
{collision} |
chronicle-sql-upsert-collisions-recovered |
sql.composite_key.stamp_failures |
{failure} |
chronicle.sql.composite_key.stamp_failures |
sql.composite_key.collisions |
{collision} |
chronicle.sql.composite_key.collisions |
The meter is Cratis.Chronicle, except for the two composite-key instruments, which use Cratis.Chronicle.Storage.Sql.CompositeKeyShadow. Scope names do not change.
Metric attributes
Section titled “Metric attributes”The convention series use only the shared keys below, not both sets of keys on each measurement. Legacy series retain the legacy keys. Event source ids and partition ids remain excluded from metric dimensions in every identifier exposure mode.
| Legacy key | Shared key |
|---|---|
EventStore |
cratis.event_store.name |
Namespace |
cratis.event_store.namespace |
ObserverId |
cratis.observer.id |
EventSequenceId |
cratis.event_sequence.id |
eventName |
cratis.event_type.id |
QueueId |
cratis.chronicle.appended_events_queue.id |
Reason |
cratis.chronicle.observer.spill_reason |
divergence |
cratis.chronicle.observer.claim_divergence |
Condition |
cratis.chronicle.alert.condition |
Severity |
cratis.chronicle.alert.severity |
state |
cratis.chronicle.abandoned_delivery.result_state |
authority |
cratis.chronicle.webhook.authority |
provider |
cratis.chronicle.sql.provider |
outcome |
cratis.chronicle.sql.schema_lock.outcome |
query |
cratis.chronicle.sql.live_query.name |
kind |
cratis.chronicle.sql.live_query.failure_kind |
operation |
cratis.chronicle.sql.upsert.operation |
Span names and attributes
Section titled “Span names and attributes”Kernel span names already use cratis.chronicle.*. Their names and kinds are unchanged. Client operation and display names remain the existing client.* names by default. In .NET, set ChronicleTelemetryOptions.SpanNames to ClientSpanNames.Convention through WithTelemetry to opt in, or configure Telemetry:SpanNames as Convention. The activity source remains Cratis.Chronicle.Client. Each operation emits one span, never a legacy and a convention span together.
| Default client span | Convention client span |
|---|---|
client.event_sequence.append |
cratis.chronicle.client.event_sequence.append |
client.event_sequence.append_many |
cratis.chronicle.client.event_sequence.append_many |
client.unit_of_work.commit |
cratis.chronicle.client.unit_of_work.commit |
client.unit_of_work.rollback |
cratis.chronicle.client.unit_of_work.rollback |
client.reactor.handle |
cratis.chronicle.client.reactor.handle |
client.reducer.handle |
cratis.chronicle.client.reducer.handle |
Kernel and client spans carry the shared keys alongside their existing keys in either client naming mode. Kernel cratis.eventstore.name, cratis.eventstore.namespace, cratis.eventsequence.id, cratis.eventsource.type, cratis.eventsource.id, cratis.eventtype.id, and cratis.connection.id gain cratis.event_store.name, cratis.event_store.namespace, cratis.event_sequence.id, cratis.event_source.type, cratis.event_source.id, cratis.event_type.id, and cratis.chronicle.connection.id, respectively. Observer keys already match the convention.
Client event_store_name, namespace_name, event_sequence_id, event_source_type, event_source_id, and correlation_id gain the corresponding shared keys. Reactor and reducer ids gain cratis.observer.id and cratis.observer.type. Identifier exposure configuration applies to both copies of an event source id: hashed values are identical under both keys, and omitted ids appear under neither key.