Analytics
The MATTR VII Analytics APIs allow viewing analytic data from tenant interactions in the form of events. These events form a database that can be seen as a history of all the requests made by a tenant to the platform. The events can be generated with different ranges of data, ranging from no data up to a full response.
The Analytics service uses a standard publisher-subscriber architecture. MATTR VII services create and publish events that are pushed to a queue. The Analytics service then consumes these events and stores them in a database.
You can query the database for events and retrieve their metadata and data using either direct API requests or the Self Service Portal.
The Events registry (opens in a new tab) is a comprehensive collection of analytic events generated by the MATTR VII platform. In addition, our API Reference indicates what event types can be generated when calling each endpoint.
Events structure
The structure of MATTR VII analytic events depends on the following:
- Event type: Different event types generate different event payloads. Refer to the events registry for an inclusive list.
- Event sanitisation: MATTR VII analytics can be configured to three
different logging levels, and so each event has three possible corresponding payload versions:
- Level 1: Metadata only.
- Level 2: Non-sensitive data.
- Level 3: Full event data.
- Event version: When new versions of events are introduced (for example as a result of a change to an endpoint response payload structure), different versions of the event could have different payload structures.
Event types
MATTR VII events are usually generated in one of the following scenarios:
START
events are generated when an operation starts.SUCCESS
events are generated followingSTART
events when the operation succeeds.FAIL
events are generated followingSTART
events when the operation fails.
For example, when making a request to sign a Compact Credential, the following events might be generated:
- When a sign operation starts, a
CREDENTIAL_COMPACT_SIGN_START
event is generated.- If the sign operation succeeds, a
CREDENTIAL_COMPACT_SIGN_SUCCESS
event is generated. - If the sign operation fails, a
CREDENTIAL_COMPACT_SIGN_SUCCESS
event is generated.
- If the sign operation succeeds, a
Each event type results in a different events payload structure.
START
and SUCCESS
events
START
and SUCCESS
events return payloads of the following structure:
{
"id": "string",
"type": "literal string",
"category": "string",
"timestamp": "Long",
"version": "string",
"tenantId": "string",
"requestId": "string",
"data": "(ServiceDtoInput | ServiceDtoOutput)"
}
id
: Unique event identifier.type
: Event type. This might affect the structure of the payload. Refer to the events registry for an inclusive list.category
: Event category. Refer to the events registry for an inclusive list.timestamp
: Event start time, in ISO-8601 format.version
: Event version. This might affect the structure of the payload.tenantId
: Unique identifier of the tenant the event was generated for.requestId
: Unique identifier of the request the event is part of.data
: The request (forSTART
events) or response (forSUCCESS
events) body. The structure of this Data Transfer Object (DTO) would differ based on the endpoint which generated the event. Refer to the events registry to inspect the structure of different event types.
START
and SUCCESS
events exceptions
- Events generated by a
list
operation:START
events: Thedata
object would contain thecursor
,limit
andid
(when applicable) parameters. Refer to Pagination for more information.SUCCESS
events: Thedata
object would contain the number of entries in the response.
- Events with a large binary DTO: The data object includes either derived data, extracted meaningful data, or a reference to the data source.
FAIL events
FAIL events return payloads of the following structure:
{
"id": "string",
"type": "literal string",
"category": "string",
"timestamp": "Long",
"version": "string",
"tenantId": "string",
"requestId": "string",
"data": {
"error": {
"type": "string",
"message": "string"
}
}
}
id
: Unique event identifier.type
: Event type. This might affect the structure of the payload. Refer to the events registry for an inclusive list.category
: Event category. Refer to the events registry for an inclusive list.timestamp
: Event start time, in ISO-8601 format.version
: Event version. This might affect the structure of the payload.tenantId
: Unique identifier of the tenant the event was generated for.requestId
: Unique identifier of the request the event is part of.data
:error
:type
: Error type as defined by MATTR VII. Note that if the error is due to an exception, type will beunknown
.message
: Error message as defined by MATTR VII.
Sanitised events
When events contain sensitive information, sanitising them before they are logged or processed helps in removing or anonymising this data, thus preserving privacy.
Sanitised versions of MATTR VII analytic events can be stripped of all data, or just sensitive data. Stripped data is configured per end-points depending on the information included in the event body.
Events registry
The Events registry (opens in a new tab) is a
comprehensive collection of analytic events generated by the MATTR VII platform. Events are grouped
by the service that generates them, which corresponds to the event category
.
Two Events registry are available for the following APIs:
In each registry the following information is available for each event:
- Event
type
. - Event structure in the different logging levels:
Level 1 - Metadata
.Level 2 - Non-sensitive data
.Level 3 - Full event
.
- Event properties:
- Properties tagged with
Sanitisation Level DATA
are removed from the event structure when sanitisation level is set toLevel 1 - Metadata
. - Properties tagged with
Sanitisation Level PII
are removed from the event structure when sanitisation level is set toLevel 2 - Non-sensitive data
.
- Properties tagged with