Event Recorder

Event Recorder — Records metric events to metric system daemon.

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── EmtrEventRecorder

Includes

#include <eosmetrics/eosmetrics.h>

Description

The event recorder asynchronously sends metric events to the metric system daemon via D-Bus. The system daemon then delivers metrics to the server on a best-effort basis. No feedback is given regarding the outcome of delivery. The event recorder is thread-safe.

This API may be called from JavaScript as follows.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const EosMetrics = imports.gi.EosMetrics;
const GLib = imports.gi.GLib;
const MEANINGLESS_EVENT = "fb59199e-5384-472e-af1e-00b7a419d5c2";
const MEANINGLESS_AGGREGATED_EVENT = "01ddd9ad-255a-413d-8c8c-9495d810a90f";
const MEANINGLESS_EVENT_WITH_AUX_DATA =
  "9f26029e-8085-42a7-903e-10fcd1815e03";
let eventRecorder = EosMetrics.EventRecorder.get_default();
// Records a single instance of MEANINGLESS_EVENT along with the current
// time.
eventRecorder.record_event(MEANINGLESS_EVENT, null);
// Records the fact that MEANINGLESS_AGGREGATED_EVENT occurred for some
// duration
let timer = eventRecorder.start_aggregate_timer(
  MEANINGLESS_AGGREGATED_EVENT, null);
timer.stop()
// Records MEANINGLESS_EVENT_WITH_AUX_DATA along with some auxiliary data and
// the current time.
eventRecorder.record_event(MEANINGLESS_EVENT_WITH_AUX_DATA,
  new GLib.Variant('a{sv}', {
    units_of_smoke_ground: new GLib.Variant('u', units),
    grinding_time: new GLib.Variant('u', time)
  }););

Event submission may be disabled at runtime by setting the EOS_DISABLE_METRICS environment variable to the empty string or 1. This is intended to be set when running unit tests in other modules, for example, to avoid submitting metrics from unit test runs. It will skip submitting metrics to the D-Bus daemon, but otherwise all eos-metrics functions will report success.

Functions

emtr_event_recorder_get_default ()

EmtrEventRecorder *
emtr_event_recorder_get_default (void);

Gets the event recorder object that you should use to record all metrics.

Returns

the default EmtrEventRecorder. This object is owned by the metrics library; do not free it.

[transfer none]


emtr_event_recorder_new ()

EmtrEventRecorder *
emtr_event_recorder_new (void);

Testing function for creating a new EmtrEventRecorder in the C API. You only need to use this if you are creating an event recorder for use in unit testing.

For all normal uses, you should use emtr_event_recorder_get_default() instead.

Returns

a new EmtrEventRecorder. Free with g_object_unref() if using C when done with it.

[transfer full]


emtr_event_recorder_record_event ()

void
emtr_event_recorder_record_event (EmtrEventRecorder *self,
                                  const gchar *event_id,
                                  GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id happened at the current time. Optionally, associate arbitrary data, auxiliary_payload , with this particular instance of the event. Under no circumstances should personally-identifiable information be included in the auxiliary_payload or event_id . Large auxiliary payloads dominate the size of the event and should therefore be used sparingly. Events for which precise timing information is not required should instead be recorded using emtr_event_recorder_record_events() to conserve bandwidth.

At the discretion of the metrics system, the event may be discarded before being reported to the metrics server. The event may take arbitrarily long to reach the server and may be persisted unencrypted on the client for arbitrarily long. There is no guarantee that the event is delivered via the network; for example, it may instead be delivered manually on a USB drive. No indication of successful or failed delivery is provided, and no application should rely on successful delivery. The event will not be aggregated with other events before reaching the server.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

auxiliary_payload

miscellaneous data to associate with the event. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

emtr_event_recorder_record_event_sync ()

void
emtr_event_recorder_record_event_sync (EmtrEventRecorder *self,
                                       const gchar *event_id,
                                       GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id occurred at the current time. Behaves like emtr_event_recorder_record_event() but executes synchronously, blocking until either a timeout expires or the event recorder daemon has received the event. Generally prefer emtr_event_recorder_record_event() in UI threads, but use emtr_event_recorder_record_event_sync() instead for the sake of reliability when recording an event from a process that is about to close.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

auxiliary_payload

miscellaneous data to associate with the event. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

Since: 0.4


emtr_event_recorder_record_events ()

void
emtr_event_recorder_record_events (EmtrEventRecorder *self,
                                   const gchar *event_id,
                                   gint64 num_events,
                                   GVariant *auxiliary_payload);

Make a best-effort to record the fact that num_events events of type event_id happened between the current time and the previous such recording. Optionally, associate arbitrary data, auxiliary_payload , with these particular instances of the event. Under no circumstances should personally-identifiable information be included in the auxiliary_payload , the event_id , or num_events . Large auxiliary payloads dominate the size of the event and should therefore be used sparingly. Events for which precise timing information is required should instead be recorded using emtr_event_recorder_record_event().

At the discretion of the metrics system, the events may be discarded before being reported to the metrics server. The events may take arbitrarily long to reach the server and may be persisted unencrypted on the client for arbitrarily long. There is no guarantee that the events are delivered via the network; for example, they may instead be delivered manually on a USB drive. No indication of successful or failed delivery is provided, and no application should rely on successful delivery. To conserve bandwidth, the events may be aggregated in a lossy fashion with other events with the same event_id before reaching the server.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

num_events

the number of times the event type took place.

[in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

emtr_event_recorder_record_events_sync ()

void
emtr_event_recorder_record_events_sync
                               (EmtrEventRecorder *self,
                                const gchar *event_id,
                                gint64 num_events,
                                GVariant *auxiliary_payload);

Make a best-effort to record the fact that num_events events of type event_id happened between the current time and the previous such recording. Behaves like emtr_event_recorder_record_events() but executes synchronously, blocking until either a timeout expires or the event recorder daemon has received the event. Generally prefer emtr_event_recorder_record_events() in UI threads, but use emtr_event_recorder_record_events_sync() instead for the sake of reliability when recording events from a process that is about to close.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

num_events

the number of times the event type took place.

[in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

Since: 0.4


emtr_event_recorder_record_start ()

void
emtr_event_recorder_record_start (EmtrEventRecorder *self,
                                  const gchar *event_id,
                                  GVariant *key,
                                  GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id started at the current time. The event's stop must be reported using emtr_event_recorder_record_stop() or memory will be leaked. If starts and stops of events of type event_id can be nested, then key should be used to disambiguate the stop and any progress that corresponds to this start. For example, if one were recording how long processes remained open, process IDs would be a suitable choice for the key . Within the lifetime of each process, process IDs are unique within the scope of PROCESS_OPEN events. If starts and stops of events of type event_id can not be nested, then key can be NULL.

Optionally, associate arbitrary data, auxiliary_payload , with this particular instance of the event. Under no circumstances should personally-identifiable information be included in the auxiliary_payload or event_id . Large auxiliary payloads dominate the size of the event and should therefore be used sparingly. Events for which precise timing information is not required should instead be recorded using emtr_event_recorder_record_events() to conserve bandwidth.

At the discretion of the metrics system, the event may be discarded before being reported to the metrics server. However, an event start, the corresponding stop, and any corresponding progress either will be delivered or dropped atomically. The event may take arbitrarily long to reach the server and may be persisted unencrypted on the client for arbitrarily long. There is no guarantee that the event is delivered via the network; for example, it may instead be delivered manually on a USB drive. No indication of successful or failed delivery is provided, and no application should rely on successful delivery. The event will not be aggregated with other events before reaching the server.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

key

the identifier used to associate the start of the event with the stop and any progress.

[allow-none][in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

emtr_event_recorder_record_progress ()

void
emtr_event_recorder_record_progress (EmtrEventRecorder *self,
                                     const gchar *event_id,
                                     GVariant *key,
                                     GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id progressed at the current time. May be called arbitrarily many times between a corresponding start and stop. Behaves like emtr_event_recorder_record_start().

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

key

the identifier used to associate the event progress with the start, stop, and any other progress.

[allow-none][in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

emtr_event_recorder_record_stop ()

void
emtr_event_recorder_record_stop (EmtrEventRecorder *self,
                                 const gchar *event_id,
                                 GVariant *key,
                                 GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id stopped at the current time. Behaves like emtr_event_recorder_record_start().

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

key

the identifier used to associate the stop of the event with the start and any progress.

[allow-none][in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

emtr_event_recorder_record_stop_sync ()

void
emtr_event_recorder_record_stop_sync (EmtrEventRecorder *self,
                                      const gchar *event_id,
                                      GVariant *key,
                                      GVariant *auxiliary_payload);

Make a best-effort to record the fact that an event of type event_id stopped at the current time. Behaves like emtr_event_recorder_record_stop() but executes synchronously, blocking until a timeout expires or the event recorder daemon has received the event sequence. Generally prefer emtr_event_recorder_record_stop() in UI threads, but use emtr_event_recorder_record_stop_sync() instead for the sake of reliability when recording an event sequence from a process that is about to close.

Parameters

self

the event recorder.

[in]

event_id

an RFC 4122 UUID representing the type of event that took place.

[in]

key

the identifier used to associate the stop of the event with the start and any progress.

[allow-none][in]

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[allow-none][in]

Since: 0.4


emtr_event_recorder_start_aggregate_timer ()

EmtrAggregateTimer *
emtr_event_recorder_start_aggregate_timer
                               (EmtrEventRecorder *self,
                                const gchar *event_id,
                                GVariant *auxiliary_payload);

Requests the metrics daemon to create an aggregate timer.

Parameters

self

an EmtrEventRecorder

 

event_id

an RFC 4122 UUID representing the type of event that took place

 

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[nullable]

Returns

a EmtrAggregateTimer.

[transfer full][nullable]


emtr_event_recorder_start_aggregate_timer_with_uid ()

EmtrAggregateTimer *
emtr_event_recorder_start_aggregate_timer_with_uid
                               (EmtrEventRecorder *self,
                                uid_t uid,
                                const gchar *event_id,
                                GVariant *auxiliary_payload);

Requests the metrics daemon to create an aggregate timer.

Parameters

self

an EmtrEventRecorder

 

uid

the UID to ascribe the event to

 

event_id

an RFC 4122 UUID representing the type of event that took place

 

auxiliary_payload

miscellaneous data to associate with the events. Must not contain maybe variants as they are not compatible with D-Bus.

[nullable]

Returns

a EmtrAggregateTimer.

[transfer full][nullable]

Types and Values

struct EmtrEventRecorder

struct EmtrEventRecorder;

This instance structure contains no public members.


struct EmtrEventRecorderClass

struct EmtrEventRecorderClass {
};

This class structure contains no public members.