Audit Web Services¶
Overview¶
The Audit web service can be used to query for audited events in the Fusion Metadata Registry, the log messages captured while each event was running, and the audit events that produced a particular transaction.
An audit event is recorded for each process the Registry runs, for example a REST API request, a structure query, a structure
submission or a user authentication. A process that performs further work records child audit events which reference the
originating event as their parent. For example, a structure submission made through the REST API records a REST_API event
with a child STRUCTURE SAVE event. The children, ancestors and logs of an event can all be retrieved using the services below.
All audit web services are available under the base path /ws/secure/audit.
Querying Audits¶
Returns a JSON Array of the audit events in the Registry, filterable by parameter.
| Entry Point | /ws/secure/audit/ |
| Access | Restricted (Admin users only) |
| Http Method | GET |
| Response Format | application/json (array of objects) see Audit JSON |
| Response Statuses | 200 - Query Ok 400 - Invalid date format 401 - Unauthorized 404 - Non numeric value for a numeric parameter |
HTTP Query Parameters¶
If no parameters are supplied all audited events are returned. As every request to the Registry is audited this can be a very large response, so it is strongly recommended that the limit parameter, or a date range, is used to restrict it.
Multiple filters are combined (a matching event must satisfy all of them). Text filters are not case sensitive.
| Request Parameter | Purpose |
|---|---|
| process_start | The earliest audit event to return (events which started on or after this time). The value can be specified as the epoch time in milliseconds (e.g. 1609459200000 is the start of the year 2021), a date (yyyy-MM-dd), or a date time (e.g. 2021-01-01T00:00:00 or 2021-01-01T00:00:00.000Z). A date is taken to be the start of that day. |
| process_end | The latest audit event to return (events which ended on or before this time). The value can be specified in the same formats as process_start. A date is taken to be the end of that day. |
| limit | The maximum number of audits to return, must be a positive integer. When the limit is applied, the most recent audit events are returned. |
| username | Username of the user that caused the audit event, e.g. admin, or guest for unauthenticated requests. The match is not case sensitive |
| process_id | The process that was audited, see Process Ids and Event Types |
| event_type | The type of event within the process, see Process Ids and Event Types |
| ip | The IP address of the client that caused the audit event |
| status | The outcome of the event as an HTTP status code, e.g. 200 for success, or 404 to find queries which returned no results |
| min_duration | The minimum duration of the event in milliseconds, can be used to find slow running processes |
| max_duration | The maximum duration of the event in milliseconds |
| software_version | The version of the Fusion Metadata Registry that recorded the event, e.g. 12.4.0 |
| parent | The UID of a parent audit event, returns only the audit events which are direct children of this event |
| children | true to also include the child audit events of each matching event, the default is false |
| ancestors | true to also include the parent (and further ancestor) audit events of each matching event, the default is false |
The audit events in the response are ordered by start time, in ascending order (oldest first).
Audit events returned by this query are summaries: the properties of each event are output as an empty object. To obtain the properties of an event, query it by its UID (see Query an Audit event).
Note: the audit events which produced a transaction (structure, metadata and data registration changes) are not returned by this query. Use Query the Audit event for a Transaction to obtain them.
Example¶
Return the 20 most recent structure queries which found no results:
/ws/secure/audit/?process_id=SDMX_GET&event_type=structure&status=404&limit=20
Return all the events recorded for the user admin on 9th September 2026:
/ws/secure/audit/?username=admin&process_start=2026-09-09&process_end=2026-09-09
Query an Audit event¶
This web service is used to obtain a specific audit event by its unique identifier (UID). Unlike Querying Audits, the response includes the full properties of each audit event.
| Entry Point | /ws/secure/audit/{uid} |
| Access | Restricted (Admin users only) |
| Http Method | GET |
| Response Format | application/json (array of objects) see Audit JSON |
| Response Statuses | 200 - Query Ok 401 - Unauthorized |
Path Parameters¶
| Path Parameter | Purpose |
|---|---|
| uid | The unique audit Id (UID) see Audit JSON |
HTTP Query Parameters¶
| Request Parameter | Purpose |
|---|---|
| children | true to also include the child audit events, the default is false |
| ancestors | true to also include the parent (and further ancestor) audit events, the default is false |
The response is always an array, ordered by start time in ascending order. If no audit event exists with the given UID an empty array is returned.
Example¶
/ws/secure/audit/f87bb87b-0d6b-49fe-85f7-7364304a7b3c?children=true
Query the Audit event for a Transaction¶
This web service is used to obtain the audit events for a transaction (a transaction is where the Registry updates either structural metadata, metadata, or a data registration).
| Entry Point | /ws/secure/audit/tx/{txId} |
| Access | Restricted (Admin users only) |
| Http Method | GET |
| Response Format | application/json (array of objects) see Audit JSON |
| Response Statuses | 200 - Query Ok 400 - Invalid transaction Id (must be 1 or greater) 401 - Unauthorized 404 - No transaction exists with the given Id, or the Id is not a number |
Path Parameters¶
| Path Parameter | Purpose |
|---|---|
| txId | The transaction ID, a positive integer (see the RSS feed) |
The response contains the audit event that performed the transaction, together with all of its ancestor and child audit events, ordered by start time in ascending order. The full properties of each audit event are included.
For example, a structure submission made through the REST API returns two audit events: the REST_API POST request, and its
child STRUCTURE SAVE event.
Example¶
/ws/secure/audit/tx/30
Query the Logs for an Audit event¶
This web service is used to obtain the log messages that were captured while an audit event was running.
| Entry Point | /ws/secure/audit/log/{uid} |
| Access | Restricted (Admin users only) |
| Http Method | GET |
| Response Format | application/json (array of objects) see Log JSON |
| Response Statuses | 200 - Query Ok 401 - Unauthorized |
Path Parameters¶
| Path Parameter | Purpose |
|---|---|
| uid | The unique audit Id (UID) see Audit JSON |
HTTP Query Parameters¶
| Request Parameter | Purpose |
|---|---|
| children | true to also include the logs of the child audit events, the default is false |
| ancestors | true to also include the logs of the parent (and further ancestor) audit events, the default is false |
Log messages are ordered by time, in ascending order. If there are no logs for the audit event, or no audit event exists with the given UID, an empty array is returned.
Log messages are held against the audit event that wrote them, which is often a child event. For example the logs for a
structure submission belong to the STRUCTURE SAVE event, not the REST_API event that is its parent, so use
children=true when querying the logs of a top level event.
To obtain the logs for a transaction, first obtain the audit events for the transaction (see
Query the Audit event for a Transaction), then query the logs using the uid of
the first audit event in the response with children=true&ancestors=true.
Example¶
/ws/secure/audit/log/f87bb87b-0d6b-49fe-85f7-7364304a7b3c?children=true&ancestors=true
Access¶
The audit web services require the user to be authenticated as an Admin (or the root) user, for example using HTTP Basic authentication. A request made without credentials, with invalid credentials, or by a user without Admin rights (including Agency users), is rejected with a 401 response.
If security is not enabled for the Registry, the audit web services are available to all users.
Error Responses¶
If a request fails, the response status is set as described for each service, and the body contains a JSON object describing the
error, for example the response to /ws/secure/audit/tx/99999 where no such transaction exists has a status of 404 and the
following body:
{
"Error": ["No results found for transaction '99999'"],
"Status": 404
}
A request with a non numeric value for a numeric path or query parameter (for example /ws/secure/audit/tx/abc or limit=abc)
is rejected with a 404 response containing the Registry's HTML error page, not a JSON object.
Audit JSON¶
Each audit event is output as a JSON Object which contains the following information
{
"uid": "f87bb87b-0d6b-49fe-85f7-7364304a7b3c",
"process_id": "REST_API",
"thread": "http-nio-8179-exec-1",
"event_type": "POST",
"username": "admin",
"ip": "172.24.0.1",
"process_start": 1788952424897,
"process_end": 1788952425068,
"duration": 171,
"status": 200,
"vmid": "a6ef587d817cffbb:-72862e48:1a085daa961:-8000",
"machine_id": "fmr12/172.24.0.4",
"software_version": "12.4.0",
"properties": {
"HttpHeaders": {
"host": "localhost:8179",
"accept": "application/json, text/javascript, */*; q=0.01",
"content-type": "application/json",
"user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/152.0.0.0 Safari/537.36"
},
"Path": "/ws/registry",
"PathInfo": "/json/save",
"HttpStatus": 200
}
}
Fields with no value are omitted from the output. In particular, a top level event has no parent, and a child event only contains the uid, parent, process_id, thread, event_type, username, process_start, process_end, duration, status and properties fields, for example
{
"uid": "506a0ddc-4789-4006-bde4-5f2c3cd6e664",
"parent": "f87bb87b-0d6b-49fe-85f7-7364304a7b3c",
"process_id": "STRUCTURE",
"thread": "http-nio-8179-exec-1",
"event_type": "SAVE",
"username": "admin",
"process_start": 1788952424944,
"process_end": 1788952425050,
"duration": 106,
"status": 200,
"properties": {}
}
| Field | Description |
|---|---|
| uid | The unique identifier of the audit event |
| parent | The UID of the parent audit event, omitted if this is a top level event |
| process_id | The process that was audited, see Process Ids and Event Types |
| thread | The name of the server thread the process ran on |
| event_type | The type of event within the process, see Process Ids and Event Types |
| username | Username of the user that caused the audit event, guest for unauthenticated requests, or SYSTEM for processes run by the Registry itself |
| ip | The IP address of the client that caused the audit event (top level events only) |
| process_start | The time the event started, as epoch time in milliseconds |
| process_end | The time the event ended, as epoch time in milliseconds |
| duration | The duration of the event in milliseconds |
| status | The outcome of the event as an HTTP status code (e.g. 200 success, 404 not found, 500 server error) |
| vmid | Identifier of the Java Virtual Machine that ran the process (top level events only) |
| machine_id | Identifier of the server that ran the process (top level events only) |
| software_version | The version of the Fusion Metadata Registry that recorded the event (top level events only) |
| properties | A JSON Object of additional information recorded by the process, the content depends on the process. For a REST_API event this includes the Path, PathInfo, QueryParameters, HttpHeaders and HttpStatus of the request. If a process fails with an uncaught error the details are recorded under the UncaughtException property. Always an empty object in the response to Querying Audits |
Log JSON¶
Each log message is output as a JSON Object which contains the following information
{
"AuditId": "506a0ddc-4789-4006-bde4-5f2c3cd6e664",
"Level": 2,
"Logger": "io.sdmx.core.fmr.engine.structure.RegistryStructureValidationEngine",
"Message": "Validate structures for insertion",
"Thread": "http-nio-8179-exec-1",
"LogTime": 1788952424952
}
| Field | Description |
|---|---|
| AuditId | The UID of the audit event the log message belongs to |
| Level | The log level: 0 TRACE, 1 DEBUG, 2 INFO, 3 WARN, 4 ERROR |
| Logger | The name of the logger which wrote the message |
| Message | The log message |
| Thread | The name of the server thread which wrote the message |
| LogTime | The time the message was logged, as epoch time in milliseconds |
Process Ids and Event Types¶
The following table lists the main process ids and event types recorded by the Registry, which can be used with the process_id and event_type query parameters (the match is not case sensitive).
| process_id | event_type | Description |
|---|---|---|
| REST_API | The HTTP method, e.g. GET, POST, DELETE | A request to a Registry web service |
| SDMX_GET | The type of query, e.g. structure, schema | An SDMX REST API query, recorded as a child of the REST_API event |
| SDMX_POST | The type of submission, e.g. metadata | An SDMX REST API submission, recorded as a child of the REST_API event |
| STRUCTURE | SAVE, DELETE, AFTER_COMMIT | A change to structural metadata |
| METADATA | SAVE, DELETE | A change to metadata |
| REGISTRATION | APPEND, REPLACE, DELETE | A change to a data registration |
| SECURITY | AUTHENTICATE | A user authentication |
| RESTORE | A restore of the Registry content | |
| APPLICATION_START | START, START_CLASS | Processes run while the Registry is starting |
Changes from previous versions¶
The following web services have been removed. The table shows the service to use instead.
| Removed Service | Replacement |
|---|---|
| /ws/secure/audit/searchAudits | /ws/secure/audit/ - note the query parameters have changed, e.g. dateFrom / dateTo are replaced by process_start / process_end, max by limit, and user by username |
| /ws/secure/audit/getDetailsByTransactionId?txId= | /ws/secure/audit/tx/{txId} - note the response is now an array of audit events in the Audit JSON format |
| /ws/secure/audit/downloadLogsForTransaction?txId= | Obtain the audit events with /ws/secure/audit/tx/{txId}, then their logs with /ws/secure/audit/log/{uid} |
| /ws/secure/audit/downloadLogsForAudit?uid= | /ws/secure/audit/log/{uid} - note the logs are now returned as JSON |