Request 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.
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.
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 }
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.
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:
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
The resulting details can be captured in several places:
X-RequestTrace header.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 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.
If needed, request headers can be used to capture the source information when performing write operations. See Capturing Source Information for more details.
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 |
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:
X-Request-ID header is not present, a randomly generated request ID will be created and stored automatically.Meta.source value is not present, no Source URI will be stored.