Top | ![]() |
![]() |
![]() |
![]() |
EmtrEventRecorder * | emtr_event_recorder_get_default () |
EmtrEventRecorder * | emtr_event_recorder_new () |
void | emtr_event_recorder_record_event () |
void | emtr_event_recorder_record_event_sync () |
void | emtr_event_recorder_record_events () |
void | emtr_event_recorder_record_events_sync () |
void | emtr_event_recorder_record_start () |
void | emtr_event_recorder_record_progress () |
void | emtr_event_recorder_record_stop () |
void | emtr_event_recorder_record_stop_sync () |
EmtrAggregateTimer * | emtr_event_recorder_start_aggregate_timer () |
EmtrAggregateTimer * | emtr_event_recorder_start_aggregate_timer_with_uid () |
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.
EmtrEventRecorder *
emtr_event_recorder_get_default (void
);
Gets the event recorder object that you should use to record all metrics.
the default EmtrEventRecorder. This object is owned by the metrics library; do not free it.
[transfer none]
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.
a new EmtrEventRecorder.
Free with g_object_unref()
if using C when done with it.
[transfer full]
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.
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.
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
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.
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] |
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.
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
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.
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] |
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()
.
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] |
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()
.
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] |
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.
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
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.
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.