Access Logs

Akana supports NCSA‑format access logs, JSON‑format access logs, and Elasticsearch appender‑based access logs for collecting access‑log data. Access logs help support traffic analytics, performance monitoring, security auditing, and capacity planning.

On this page:

NCSA-format access logs

Akana supports generating container access logs in NCSA Common Log Format. You can enable these logs by using the Admin Console or a recipe.

Enable logging by using the Admin Console

  1. Log in to the Admin Console.
  2. Go to Configuration > Configuration Categories > com.soa.platform.jetty.
  3. Enable and set the following properties on each container where you want to manage NCSA access logs:
    • NCSA Access Log (ncsa.access.log.writer.enable) - Set to true to enable the NCSA access log writer.
    • NCSA File Access Log (ncsa.access.log.enable) - Set to true to generate log files in NCSA format.
    • Extended Log Format (ncsa.access.log.extended) - Set to true if you need additional fields included in the logs.
    • NCSA Access Log Filename (ncsa.access.log.filename) - Specify the filename pattern. Include the string yyyy_mm_dd, which is replaced with the actual date during file creation and rollover.
    • NCSA Access Log Retention (ncsa.access.log.retainDays) - Set the number of days to retain log files.
    • NCSA Access Log Append (ncsa.access.log.append) - Choose whether to append to existing log files or overwrite them.
    • NCSA Access Log Latency (ncsa.access.log.logLatency) - Enable this to include request processing time in the access log.

Enable logging by using a recipe

You can also enable NCSA access logs by creating a configuration‑properties recipe that sets the required logging properties. The following is a sample recipe file.

Copy 
{
  "name":"Update NCSA log configurator",
  "description":"log appender configurator to [ enable ] NCSA logs. Default this log is disabled",
  "phases":["finalize"],
  "configurations":[
    {
      "pid":"com.soa.platform.jetty",
      "update":{
        "ncsa.access.log.writer.enable":"true",
        "ncsa.access.log.enable:"true",
        "ncsa.access.log.extended":"false",
        "ncsa.access.log.filename":"true",
        "ncsa.access.log.retainDays":"30",
        "ncsa.access.log.append":"true",
        "ncsa.access.log.logLatency":"true",
      }
    }
  ]
}

NCSA log format

The Extended (or Combined) NCSA log format is a widely adopted, de facto standard for web server access logs. It extends the Common Log Format (CLF) by adding "Referer" and "User-Agent" fields, following the format: 

host ident authuser [date] "request" status bytes "referer" "user-agent"

Log Structure:

  • %h: Remote host (client IP).
  • %l: Remote log name (identd).
  • %u: Remote quthenticated user.
  • %t: Time of request ([DD/Mon/YYYY:HH:MM:SS +ZONE]) format.
  • "%r": First line of request (Method, URL, Protocol).
  • %>s: Final status code.
  • %b: Size of response in bytes (excluding headers).
  • "%{Referer}i": Referer header.
  • "%{User-Agent}i": User-agent browser string

The following is a typical log entry:

10.151.121.250 - - [16/Mar/2026:07:26:03 +0000] "GET /api10253live/store/inventory HTTP/1.1" 200 192 "-" "PostmanRuntime/7.51.1" 1527

JSON-format access logs

The JSON-format access logs deliver clean structured log data. You can enable or disable JSON-format access logging by using the recipe.

Configure the Log4j access log based on the JSON-format

Use the following recipe to configure the Log4j access log to generate logs in JSON format. Run the recipe by using the following structure:

./jython.sh -m akana.container --recipe ../recipes/access-log-json-template-logger-config.json --name <container-name> --home <application-runtime-path>

Disable the Log4j access log appender

Run the recipe by using the following structure:

./jython.sh -m akana.container --recipe ../recipes/disable-log-appender-configurator.json --name <container-name> --home <application-runtime-path>

Running this recipe in its default configuration disables the jsonRolling log appender. Do not run it in default mode if your intention is only to disable the Log4j access log.

To disable the Log4j access log appender, update the disable-log-appender-configurator.json in the recipe directory and then run the recipe.

The following shows an existing content of the disable-log-appender-configurator.json.

Copy 
{
  "name":"Disable log appender configurator",
  "description":"log appender configurator to [ disable ] log4j appenders. Default is to disable json rolling appender for container log. Here you can change the type:object inside delete to disable other loggers as well ",
  "phases":["finalize"],
  "configurations":[
    {
      "pid":"com.soa.log",
      "delete":{
        "rootLogger.appenderRef.jsonRolling.ref":"null"
      }
    }
  ]
}

Replace:

"rootLogger.appenderRef.jsonRolling.ref":"jsonRolling" with "logger.access.appenderRef.access.ref":"null"

This change ensures that only the Log4j access log appender is disabled, while all other logger‑related properties in the com.soa.log configuration remain unchanged.

Enable the Log4j access log appender

Use the following recipe to enable the log4j access log appender. Run the recipe by using the following structure:

./jython.sh -m akana.container --recipe ../recipes/enable-log-appender-configurator.json --name <container-name> --home <application-runtime-path>

Running this recipe with its default settings enables the jsonRolling log appender. Do not run it in default mode to enable the Log4j access log.

To enable the Log4j access log appender, update the enable-log-appender-configurator.json in the recipe directory and then run the recipe.

The following shows an existing content of the enable-log-appender-configurator.json.

Copy 
{
  "name":"Enable log appender configurator",
  "description":"log appender configurator to [ enable ] log4j appenders. Default is to enable jsonRolling appender for container log. Here you can change the type:object inside update to enable other loggers as well ",
  "phases":["finalize"],
  "configurations":[
    {
      "pid":"com.soa.log",
      "update":{
        "rootLogger.appenderRef.jsonRolling.ref":"jsonRolling"
      }
    }
  ]
}

Replace:

"rootLogger.appenderRef.jsonRolling.ref":"jsonRolling" with "logger.access.appenderRef.access.ref":"access"

This change ensures that the Log4j access log appender is re-enabled, while all other logger‑related properties in the com.soa.log configuration remain unchanged.

OOTB (Out‑of‑the‑Box) Indented log format

Akana provides an OOTB JSON log format based on the Elastic Common Schema (ECS). You can use this default format or customize it to meet the requirements of your monitoring tool. The following is an ECS-based JSON template layout for access log (access-ecs-layout-template.json).

Copy 
{
  "@timestamp": {
    "$resolver": "timestamp",
    "pattern": "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
  },
  "event": {
    "type": "access",
    "duration": {
      "$resolver": "map",
      "key": "http.request.duration"
    }
  },
  "container": {
    "name": "$${sys:container.name:-unknown}"
  },
  "client": {
    "ip": {
      "$resolver": "mdc",
      "key": "client.ip"
    }
  },
  "user_agent": {
    "original": {
      "$resolver": "mdc",
      "key": "user_agent.original"
    }
  },
  "tls": {
    "version": {
      "$resolver": "mdc",
      "key": "tls.version"
    }
  },
  "http": {
    "version": {
      "$resolver": "mdc",
      "key": "http.version"
    },
    "request": {
      "method": {
        "$resolver": "mdc",
        "key": "http.request.method"
      },
      "bytes": {
        "$resolver": "map",
        "key": "http.request.bytes"
      },
      "referrer": {
        "$resolver": "mdc",
        "key": "http.request.referrer"
      }
    },
    "response": {
      "status_code": {
        "$resolver": "map",
        "key": "http.response.code"
      },
      "bytes": {
        "$resolver": "map",
        "key": "http.response.bytes"
      }
    }
  },
  "url": {
    "path": {
      "$resolver": "mdc",
      "key": "url.path"
    }
  }
}
To use the container name in an Amazon EKS environment, replace "name": "$${sys:container.name:-unknown}" property with "name": "${CONTAINER_NAME}" in the Log4j JSON layout configuration. For more information, refer to the JSON Template Layout section in the Apache Log4j documentation.

A JSON‑based access log generated by Log4j appears in the following format:

{"@timestamp":"2026-03-10T18:07:06.410+0530","event":{"type":"access","duration":1473},"container":{"name":"eapNd"},"client":{"ip":"127.0.0.1"},"user_agent":{"original":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"},"tls":{"version":"1.3"},"http":{"version":"1.1","request":{"method":"GET","referrer":"http://open.soa.com:7900/atmosphere/"},"response":{"status_code":200,"bytes":175}},"url":{"path":"/api10014live/store/inventory"}}

In the 2026.1.0 release, NCS and JSON‑format access logs use timestamps that may differ slightly in value.

Customize default access log format

You can add or remove fields from the JSON‑based Log4j access log by updating the access-ecs-layout-template.json file. After each update, run the recipe that configures the JSON-format Log4j access log.

Run the recipe by using the following structure:

./jython.sh -m akana.container --recipe ../recipes/access-log-json-template-logger-config.json --name <container-name> --home <application-runtime-path>

Add additional fields from environment variables

You can add custom fields from environment variables to the JSON‑based Log4j access log by updating the access-ecs-layout-template.json file.

To add custom fields

  1. Locate and open the access-ecs-layout-template.json file in the recipe directory.
  2. Add the field definition to the template. For example, to include the container field, add the following in the JSON file:
    Copy
    "container": {
      "name": "$${sys:container.name:-unknown}"
    },

  3. Save the JSON file.

  4. Run the recipe.
    ./jython.sh -m akana.container --recipe ../recipes/access-log-json-template-logger-config.json --name <container-name> --home <application-runtime-path>

Add additional fields from ThreadContext

You can add fields from ThreadContext to the JSON-based access log by updating the access-ecs-layout-template.json file. For example, to include the client.ip field, add the following to the JSON access‑log template.

Copy 
"client": {
  "ip": {
    "$resolver": "mdc",
    "key": "client.ip"
  }

Save the file and run the recipe.

./jython.sh -m akana.container --recipe ../recipes/access-log-json-template-logger-config.json --name <container-name> --home <application-runtime-path>

Remove fields from the access log layout

You can remove fields from the JSON‑based access‑log layout by updating the access-ecs-layout-template.json file. Delete the field definitions you no longer want to include in the log output.

Take the following steps:

  1. Locate and open the access-ecs-layout-template.json file in the recipe directory.
  2. Find the field you want to remove. For example: "client", "container", or other custom fields.
  3. Delete the field definition.
  4. Save the updated template.
  5. Apply the changes by running the following recipe:
    ./jython.sh -m akana.container --recipe ../recipes/access-log-json-template-logger-config.json --name <container-name> --home <application-runtime-path>

Elasticsearch appender-based access logs

You can configure Elasticsearch appender to write access logs directly to Elasticsearch. For more information, see Configuring the Elasticsearch Log Plug-In to Write Access Logs to Elasticsearch.

Configure Auditing to capture message data

Additional details from API request, response, or fault messages can be captured by using the Auditing Service Policy. This policy allows Akana‑hosted APIs to log message‑level information beyond the standard access log.