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 MATTR Portal.

The Events registry 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 sanitization: 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 CWT 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_FAIL 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",
    "clientIds": "string",
    "managementUserIds": "string",
    "requestIp": "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.
• clientIds : Unique identifier of the client who initiated the request.
• managementUserIds : Unique identifier of the management user who initiated the request.
• requestIp : IP address from which the request was made.
• 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",
    "clientIds": "string",
    "managementUserIds": "string",
    "requestIp": "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.
• clientIds : Unique identifier of the client who initiated the request.
• managementUserIds : Unique identifier of the management user who initiated the request.
• requestIp : IP address from which the request was made.
• 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.

Sanitized events

When events contain sensitive information, sanitizing them before they are logged or processed helps in removing or anonymizing this data, thus preserving privacy.

Sanitized 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.

When you are reading an event, remember that a field you expected to see may have been removed by sanitization rather than being absent from the operation itself. Check the Events registry to see which properties are stripped at your tenant's logging level before concluding that MATTR VII did not receive or produce a value.

Correlating events

A single operation emits more than one event, and a single user journey usually spans more than one operation. Three identifiers let you group those events back together, each at a different scope.

requestId

MATTR VII generates a request ID for each call it receives and returns it in the x-request-id response header. The same value travels with the request through every internal service involved in serving it, including calls MATTR VII makes out to your own systems on your behalf, such as a request to a claims source. Querying by request ID therefore reconstructs the server-side trace for a single HTTP call.

Log the x-request-id response header on every MATTR VII call your backend makes. It is the quickest way to find the events for a specific call later, and it is the first thing our support team asks for.

sessionId

Many MATTR VII flows are made up of several separate HTTP calls. An OID4VCI issuance, for example, involves your backend creating a credential offer, then the wallet exchanging a pre-authorized code for an access token, then the wallet requesting the credential. Each of those is a separate call with its own request ID. The sessionId is what ties them together into a single journey.

Not every event carries a sessionId. Refer to the Events registry to check a specific event type.

Filtering by identifier

The id and requestId fields sit at the top level of an event, so you can filter on them directly using the ids and requestIds query parameters. The sessionId sits inside data, which is not a filterable field. To group events by session, query by event type over a time window and then match on data.sessionId in your own code.

Refer to How to query analytic events for the available query parameters, and to How to monitor a flow for how to apply these identifiers when investigating a flow.

Events registry

The Events registry 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
• Management API

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