Configure F5 AI Gateway logging¶

This page describes how to configure logging for F5 AI Gateway.

AI Gateway writes information about events of different severity levels to it’s log.

The AI Gateway logging configuration block specifies where logs should be written, the minimum severity level and which record fields should be included.

AI Gateway writes all records to stdout in the json format by default.

Refer to the examples section to see multiple configuration invariants and the resulting logger output.

Level¶

Log Levels represents the importance of a log event. The higher the level, the more important the event.

F5 AI Gateway defines four log levels with info being the default.

Level	Description	Severity
debug	debug events communicate detailed information about encounters which may be useful when deubbing unexpected behavior.	lowest
info	info events communicate high level details about encounters.	low
warn	warn events communicate unexpected encounters.	high
error	error events communicate issues which were encountered.	highest

Output Handler¶

F5 AI Gateway log handlers are repsonsible for log record formatting, filtering and writing.

F5 AI Gateway ships with a single log output formatter, console, which can be configured with the following options:

format - specifies the log record format to be either json or text; json being the default.
writer - specifies which console stream, stdout or stderr to write to; stdout being the default.

See Log Samples below for examples configurations and log outputs.

Context¶

The Context configuration specifies a set a stable field names to be included in the log records emitted by the logger.

Non-standard, record-specific, fields are grouped together under the field labeled details.

Context Keys¶

Key	Type	Description
commit	string	F5 AI Gateway git ref.
details	string	Additonal details specific to a particular Log Record.
error	string	Error cause.
instance	string	F5 AI Gateway running configuration digest(sha256 sum).
level	string	Log Record Priority. Possible log levels in ascending order of priority: debug, info, warn and error.
logger	string	Logger instance name; currently only one logger is supported with the name ‘root’.
msg	string	Log Record message.
phase	string	F5 AI Gateway Profile phase of execution; One of input, upstream or output.
processor	string	F5 AI Gateway Processors name.
request_id	string	HTTP request identifier.
service	string	F5 AI Gateway Service name.
route	string	F5 AI Gateway Request Handler endpoint.
stage	string	F5 AI Gateway Stage of execution. Each Phase is comprised of one or more named stages.
time	string	Log Record timestamp in the RFC3339 format with millisecond precision.
trace_id	string	Distributed Trace context identifier.
version	string	F5 AI Gateway version.

Examples¶

Log sample setup¶

The samples in this section have been generated using the following curl request (Replace http://example.com/api/v1/chat with a URL to a real AI Gateway installation to test it in your own environment):

Client Request:

  curl -H "Content-Type: application/json" http://example.com/api/v1/chat -d '{"messages":[{"role":"user","content":"What makes docs great?"}]}'

F5 AI Gateway Profile:

profiles:
  - name: logging
    inputStages:
      - name: preflight
        concurrency: parallel
        steps:
          - name: prompt-injection
          - name: repetition-detect

    services:
      - name: ollama/any

Default output¶

2025-02-24 14:17:31 {"time":"2025-02-24T19:17:31.107981547Z","level":"INFO","msg":"executing stage","request_id":"01953964-a163-70d4-aa7b-c3c09b9d4bc8","details":{"name":"preflight","concurrency":1}}
2025-02-24 14:17:31 {"time":"2025-02-24T19:17:31.108326464Z","level":"INFO","msg":"executing processor","request_id":"01953964-a163-70d4-aa7b-c3c09b9d4bc8","details":{"name":"repetition-detect"}}
2025-02-24 14:17:31 {"time":"2025-02-24T19:17:31.108321797Z","level":"INFO","msg":"executing processor","request_id":"01953964-a163-70d4-aa7b-c3c09b9d4bc8","details":{"name":"prompt-injection"}}
2025-02-24 14:17:31 {"time":"2025-02-24T19:17:31.410387964Z","level":"INFO","msg":"executing ollama service","request_id":"01953964-a163-70d4-aa7b-c3c09b9d4bc8","details":{"type":"qwen:0.5b"}}

Text formatted output¶

logging:
  output_handler:
    config:
      format: text

2025-02-24 14:21:10 time=2025-02-24T19:21:10.120Z level=INFO msg="executing stage" request_id=01953967-f8e7-7ebb-a07a-143a29c39dd3 details.name=preflight details.concurrency=1
2025-02-24 14:21:10 time=2025-02-24T19:21:10.120Z level=INFO msg="executing processor" request_id=01953967-f8e7-7ebb-a07a-143a29c39dd3 details.name=repetition-detect
2025-02-24 14:21:10 time=2025-02-24T19:21:10.120Z level=INFO msg="executing processor" request_id=01953967-f8e7-7ebb-a07a-143a29c39dd3 details.name=prompt-injection
2025-02-24 14:21:10 time=2025-02-24T19:21:10.361Z level=INFO msg="executing ollama service" request_id=01953967-f8e7-7ebb-a07a-143a29c39dd3 details.type=qwen:0.5b

Custom Log Context¶

logging:
  context:
    - time
    - level
    - msg
    - route
    - request_id
    - commit
    - instance
    - details
    - error

{"time":"2025-02-24T19:23:29.558738338Z","level":"INFO","msg":"executing stage","commit":"5f2d5b8a","instance":"WJl3M+j99gmy1SiR+79kOaT1bIlEcY0k5CeP/GWzyaQ=","request_id":"0195396a-1996-752f-84d9-70b60d47d13e","route":"/api/v1/chat","details":{"name":"preflight","concurrency":1}}
{"time":"2025-02-24T19:23:29.558865838Z","level":"INFO","msg":"executing processor","commit":"5f2d5b8a","instance":"WJl3M+j99gmy1SiR+79kOaT1bIlEcY0k5CeP/GWzyaQ=","request_id":"0195396a-1996-752f-84d9-70b60d47d13e","route":"/api/v1/chat","details":{"name":"repetition-detect"}}
{"time":"2025-02-24T19:23:29.559406921Z","level":"INFO","msg":"executing processor","commit":"5f2d5b8a","instance":"WJl3M+j99gmy1SiR+79kOaT1bIlEcY0k5CeP/GWzyaQ=","request_id":"0195396a-1996-752f-84d9-70b60d47d13e","route":"/api/v1/chat","details":{"name":"prompt-injection"}}
{"time":"2025-02-24T19:23:29.77501263Z","level":"INFO","msg":"executing ollama service","commit":"5f2d5b8a","instance":"WJl3M+j99gmy1SiR+79kOaT1bIlEcY0k5CeP/GWzyaQ=","request_id":"0195396a-1996-752f-84d9-70b60d47d13e","route":"/api/v1/chat","details":{"type":"qwen:0.5b"}}

Change Log Level¶

logging:
  level: debug

{"time":"2025-01-02T09:39:13.788133-05:00","level":"DEBUG","msg":"checking processor","details":{"endpoint":"https://example.ai/api/v1/signature/f5/language-id"}}
{"time":"2025-01-02T09:39:13.788803-05:00","level":"DEBUG","msg":"checking processor","details":{"endpoint":"https://example.ai/api/v1/signature/f5/repetition-detect"}}
{"time":"2025-01-02T09:39:13.788827-05:00","level":"DEBUG","msg":"checking processor","details":{"endpoint":"https://example.ai/api/v1/signature/f5/prompt-injection"}}
{"time":"2025-01-02T09:39:28.787048-05:00","level":"DEBUG","msg":"checking processor","details":{"endpoint":"https://example.ai/api/v1/signature/f5/language-id"}}

Full Logger Configuration¶

logging: 
  level: info
  context:
    - time
    - level
    - msg
    - route
    - request_id
    - details
    - error
  output_handler:
    type: console
    config:
      format: text
      stream: stderr

2025-02-24 14:33:35 time=2025-02-24T19:33:35.973Z level=INFO msg="executing stage" request_id=01953973-5a65-712d-acfd-5faeccf00472 route=/api/v1/chat details.name=preflight details.concurrency=1
2025-02-24 14:33:35 time=2025-02-24T19:33:35.973Z level=INFO msg="executing processor" request_id=01953973-5a65-712d-acfd-5faeccf00472 route=/api/v1/chat details.name=repetition-detect
2025-02-24 14:33:35 time=2025-02-24T19:33:35.974Z level=INFO msg="executing processor" request_id=01953973-5a65-712d-acfd-5faeccf00472 route=/api/v1/chat details.name=prompt-injection
2025-02-24 14:33:36 time=2025-02-24T19:33:36.263Z level=INFO msg="executing ollama service" request_id=01953973-5a65-712d-acfd-5faeccf00472 route=/api/v1/chat details.type=qwen:0.5b

Previous Next