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 following START events when the operation succeeds.
• FAIL events are generated following START 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.

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 (for START events) or response (for SUCCESS 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: The data object would contain the cursor, limit and id (when applicable) parameters. Refer to Pagination for more information.
  • SUCCESS events: The data 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 be unknown.
    • 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:

• MATTR VII API (opens in a new tab)
• Management API (opens in a new tab)

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 to Level 1 - Metadata.
  • Properties tagged with Sanitisation Level PII are removed from the event structure when sanitisation level is set to Level 2 - Non-sensitive data.

Additional resources

Guides

API Reference