Logging

SDL Developers are required to adhere to a standardized logging format in support of ATO / STIG compliance. Given that SDL applications are language agnostic, the following document outlines a JSON logging format with example implementations in a variety of languages found within the system. Where possible, usage of existing logging libraries or creation of library wrappers around these tools is encouraged.

Format and Content Requirements

All log events must be JSON and minimally contain the following fields:

Required Fields

  • level

    • Severity level of the emitted event

    • Actual values are library dependent, but should generally be FATAL, ERROR, WARN, INFO, DEBUG, or TRACE

  • time

    • ISO 8601 UTC timestamp minimally with millisecond precision

    • Format: YYYY-MM-DDTHH:mm:ss.sssZ

  • appId

    • A unique application identifier

  • appVersion

    • The application version

  • class

    • The fully qualified class name, including the package/module

  • method

    • The calling function or method

  • line

    • Line number of the log event occurrence

  • message

    • The message for the event, subject to additional requirements depending on context

  • entity

    • The entity, username, or user ID associated with the event

    • For applications or code where this information is not applicable, use a value of system

Optional Fields

Additional fields can be specified on a per-application basis. For example:

  • traceId

    • If set, used to correlate a chain of events across different services

    • For example, a traceId may be generated by a user interacting with an API endpoint. This traceId is then passed to all follow-on calls across downstream services so that a single lineage can be constructed

    • Trace IDs may be particularly useful for correlating logs within Pipelines

  • spanId

    • If set, used to identify a specific operation within a trace

Log Event Emit Requirements

  • Log events marked with an appropriate severity level and runtime configuration ensure that only events up to the desired level are reported

  • Within the application, a log event must be generated for any data access or modification by a user

    • For example, an API service must log the user and action taken on a given endpoint

  • When communicating with an external service, the service name and IP address must be logged

  • Sensitive information such as tokens or passwords must not be logged. If a message is emitted with this information, the content must be masked

Language-Specific Logging Libraries

The following libraries are easily configured to adhere to the above format and content restrictions:

Sample Log Events

Standard Application Event

{
  "level": "DEBUG",
  "time": "2025-03-15T12:15:40.555Z",
  "appId": "json-processor",
  "appVersion": "v1.0.0",
  "class": "com.example.processing.DataHandler",
  "method": "transformJsonData",
  "line": 99,
  "message": "Attempting to transform json data '{\"key\":\"val\"}'",
  "entity": "system",
  "traceId": "a64af53a-acb4-4db3-b328-c9e504b0e1d1",
  "spanId": "16e2dcfa-2be6-49ab-8a21-a8841a77b020"
}

Standard User Event

{
  "level": "INFO",
  "time": "2024-01-15T14:30:25.123Z",
  "appId": "user-service",
  "appVersion": "v1.2.3",
  "class": "com.example.userservice.UserController",
  "method": "getUserById",
  "line": 45,
  "message": "Successfully retrieved user profile",
  "entity": "userAbc"
}

Event With Masked Sensitive Information

{
  "level": "INFO",
  "time": "2024-01-15T15:35:12.653Z",
  "appId": "user-service",
  "appVersion": "v1.2.3",
  "class": "com.example.userservice.UserController",
  "method": "authenticateUser",
  "line": 150,
  "message": "Authenticating user with token: ***",
  "entity": "userAbc"
}