Skip to main content
Previous sectionNext section

Debugging and Maintaining a FHIR Server

Debugging the FHIR Server

Putting the FHIR server in debug mode helps solve problems during development and can temporarily eliminate the need to authenticate FHIR requests.

Debug Mode

The installation and configuration utility can put the FHIR server into debug mode during development. To set the debug mode:

  1. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard

    Where FHIRNamepace is the name of the endpoint’s namespace.

  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 3) Configure a FHIRServer Endpoint.

  4. Accept the default options until you reach the option DebugMode.

  5. Enter a value to set the debug mode for the endpoint. The possible values are:

    DebugMode Value Description
    0 Disable all DebugMode options.
    1 Include traceback, which responds to a FHIR request by sending a stack trace in an OperationOutcome resource.
    2 Creates a new instance for the FHIR Service on each REST request.
    4 Allow unauthenticated requests.

    To enable more than one debug mode, enter a value that is the sum of multiple option values. For example, to include traceback (option 1) and allow unauthenticated requests (option 4), specify 5 as the DebugMode value.

To disable debugging, run the configuration utility again, choosing 0 as the DebugMode.

Logging

The FHIR server provides two types of logging:

  • Internal FHIR Server Logging — Provides information about how the FHIR server architecture is processing FHIR requests, including which class methods are being called.

  • HTTP Request Logging — Provides information about the HTTP requests coming from REST clients to the FHIR server.

Internal FHIR Server Logging

The FHIR server provides basic logging information about how the architecture is processing the FHIR requests being received by the server, including which class methods are being called, SQL-related messages, and how _include searches are being handled. To enable this type of logging:

  1. Open the InterSystems Terminal.

  2. Navigate to the FHIR server’s namespace. For example, enter:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  3. Create a global, ^FSLogChannel, that specifies what type of logging information should be stored. The syntax for creating the global is:

    set ^FSLogChannel(channelType) = 1
    Copy code to clipboard

    Where channelType is one of the following:

    • Msg — Logs status messages.

    • SQL — Logs SQL-related information.

    • _include — Logs information related to searches that use the _include and _revinclude parameters.

    • all — Logs all three types of information.

    For example, to enable logging for all types of information, enter:

    set ^FSLogChannel("all") = 1.
    Copy code to clipboard
Note:

To switch to a new type of logging information (for example, from Msg to SQL), kill the existing ^FSLogChannel global before setting it again with the new channelType.

Viewing the Log

Once logging for the FHIR server architecture is enabled, the log entries are stored in the ^FSLOG global. To use the Management Portal to view the log, navigate to System Explorer > Globals and view the FSLOG global (not FSLogChannel). Make sure you are in the FHIR server’s namespace.

Each node of the global is structured like:

CurrentMethod^CurrentClass|LogType|LogMessage

For example, a log entry in a node of the ^FSLOG global might be:

"runQuery^HS.FHIRServer.Storage.Json.Interactions|SQL|Parameters: (2)"

Disabling Logging

To disable logging for the FHIR server architecture, simply kill the ^FSLogChannel global or set it to 0. For example, you can enter the following in the Terminal:

kill ^FSLogChannel
Copy code to clipboard

HTTP Request Logging

When HTTP request logging is enabled, the REST handler that is receiving requests from FHIR clients writes information about each HTTP request to the ISCLog global. To enable this type of logging:

  1. Open the InterSystems Terminal.

  2. From any namespace, enter the following commands to configure the global ^%ISCLog to start logging HTTP requests:

    set ^%ISCLOG=5 
    set ^%ISCLOG("Category","HSFHIR")=5 
    set ^%ISCLOG("Category","HSFHIRServer")=5
    Copy code to clipboard

Viewing the Log

Once logging for HTTP requests is enabled, the log entries are stored in the ^ISCLOG global, which is located in the %SYS namespace.

To use the Management Portal to view the log, navigate to System Explorer > Globals and view the ISCLOG global (not %ISCLOG). Make sure you are in the %SYS namespace.

Disabling Logging

To disable HTTP request logging, open the Terminal and enter the following command:

set ^%ISCLOG=1
Copy code to clipboard

Maintaining the FHIR Server

While maintaining a FHIR server that is in production, it might be necessary to stop processing FHIR requests to the endpoint, then re-enable the endpoint when the maintenance is complete.

To stop and re-start an endpoint:

  1. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard

    Where FHIRNamepace is the name of the endpoint’s namespace.

  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 3) Configure a FHIRServer Endpoint.

  4. Select your endpoint.

  5. At the Endpoint enabled option, specify n to stop the endpoint. If you want to re-enable the endpoint, specify y.