13.19.1Request 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.

13.19.2Request 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. The request ID is included in the log lines generated during request processing.

13.19.2.1Client 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 the following characters (any request ID with other characters will be ignored for security reasons):

• Lowercase Latin-8 letters (a-z)
• Uppercase Latin-8 letters (A-Z)
• Numbers (0-9)
• Dash (-)
• Underscore (_)
• Dot (.)

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 }

Also, client can specify request ID in the field Resource.meta.source. Source has the form: < Source URI >#< request ID >.

Smile CDR can be configured to enable preserve request ID in resource body using the preserve_request_id_in_resource_body property.

This property should be enabled if source URI contains a fragment.

13.19.2.2System Generated Request IDs

If a request does not include the X-Request-ID header or request ID is not contained in field Resource.meta.source, 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.

13.19.3Performance 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.

13.19.3.1On-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

If it is more useful for you to have the query without parameters substituted (e.g. to look up the query id), you can use the value 'redacted' in place of 'true', e.g.

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

13.19.3.2Performance 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.

13.19.4Storing Source Information

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 or field Resource.meta.source as described above, and is generated by the system if not supplied by the client.

13.19.4.1Capturing

If needed, request headers can be used to capture the source information when performing write operations. See Capturing Source Information for more details.

13.19.4.2Searching

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

13.19.4.3Example: 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 or request ID is not contained in field Resource.meta.source, 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.