On this page:

5.15Request Tracing and Provenance

 

Often a FHIR server is only one component in a larger distributed system, it is often useful to be able to trace a transaction as it moves throughout the architecture.

5.15.1Request Tracing

 

To help with analysis of transactions across a broader architecture, every FHIR request is assigned a Request ID as it is received by the FHIR Endpoint. This request ID can be assigned by the client, and will be automatically assigned by the server otherwise.

Client Assigned Request IDs

Clients may supply a Request ID by using the X-Request-ID header. The following example shows a FHIR search request with a client-supplied Request ID.

GET Patient/123
X-Request-ID: 8dUEj34hwkDNd
Accept: application/fhir+json

Note that request IDs may only contain letters and digits, as well as the following characters: -_..

FHIR responses will include the Request ID in the same header, e.g.

200 OK
Content-Type: application/fhir+json
X-Request-ID: 8dUEj34hwkDNd

{ "resourceType": "Patient", "id": "123", "active": true }

System Generated Request IDs

If a request does not include the X-Request-ID header, a request ID is automatically generated by the system.

Note that when generating a Request ID, the FHIR Endpoint does not use any cryptographic functions or a secure random number generator. The Request ID is intended for use in correlating transactions, and it is not intended to be a secure identifier.

5.15.2Performance Tracing

 

When building and testing a new system, it is often beneficial to examine the FHIR queries that it makes in order to see how the system is spending its time when performing queries and CRUD operations. Performance Tracing is a useful tool that can be used to gain insight into the internal workings of Smile CDR during these operations.

In order to enable performance tracing, the Enable Performance Tracing setting should be enabled on the FHIR Storage module.

Performance tracing can be enabled in two different trigger modes:

  • All Requests: All FHIR requests will be traced
  • On Demand: Only FHIR requests that have explicitly requested tracing will be traced.

On-Demand Triggers

When using the on-demand trigger mode, clients may request that a request be traced using either of the following:

The _requestTrace parameter can be added to the request URL, e.g: http://localhost:8000/Patient?birthDate=2019&_requestTrace=true

The X-RequestTrace-Enabled header can be added to the request headers, e.g:

GET /Patient?birthDate=2019
Accept: application/fhir+json
X-RequestTrace-Enabled: true

Performance Tracing Targets

The resulting details can be captured in several places:

  • Transaction Logs: Entries will be appended to individual records in the Transaction Log corresponding to the individual client request.
  • System Logs: Entries will be appended to the System Logs
  • Response Headers: Entries will be returned to the client in the HTTP Response Headers via the X-RequestTrace header.

5.15.3Storing Source Information

 
If you are not intending to store or query source information, you can disable this storage using the dao_config.store_source_information setting. Disabling this feature causes a small reduction in the amount of data written for each write operation.

The Resource.meta.source field exists in every resource, and is used to store basic information about the provenance of a resource (i.e. what system was used to create it). When the dao_config.store_source_information setting on the FHIR Storage module is enabled, this property will be stored for every resource that is saved.

According to the FHIR specification, the field should store a URI indicating the identity of the source system used to create the data.

In HAPI FHIR and Smile CDR, this concept is extended so that this field may optionally store two pieces of information:

  • The Source URI: This is a URI indicating the source system, as described in the FHIR specification.
  • The Request ID: This is the identity of the request transaction used to create the resource version.

The Source URI is drawn from the request resource body, in the field Resource.meta.source. The Request ID is drawn from the X-Request-ID header as described above, and is generated by the system if not supplied by the client.

The _source search parameter can be used to search for resources that have a given source value. It can be used as follows:

Style Usage Example
Source URI Search by source URI: In this search, the parameter value is simply the Source URI itself. Patient?_source=http://somesystem.example.org/foo
Request ID Search by Request ID: In this search, the parameter value is a percent-encoded hash sign (# / %23) followed by the Request ID Patient?_source=%23AD83y3ydgSSF
Source URI and Request ID Search by Source URI and Request ID: In this search, the parameter value is the Source URI followed by a percent-encoded hash sign (# / %23) followed by the Request ID Patient?_source=http://somesystem.example.org/foo%238dUEj34hwkDNd

Example: Storing Source Information

The following HTTP request shows a request that includes both a source URI and a Request ID.

POST /Patient
X-Request-ID: 8dUEj34hwkDNd
Content-Type: application/fhir+json

{
   "resourceType": "Patient",
   "meta": {
      "source": "http://somesystem.example.org/foo"
   },
   "name": {
      "family": "Simpson"
   }
}

Note that:

  • If the X-Request-ID header is not present, a randomly generated request ID will be created and stored automatically.
  • If the Meta.source value is not present, no Source URI will be stored.