Managing access logs

Access logs help you troubleshoot call failures, track request latency, and audit model access behavior. By default, Neutree stores access logs in victorialogs, with a retention period of 30 days. For Kubernetes deployments, the default storage capacity is 40 GiB. You can adjust the access log retention period and storage capacity during deployment. If log data fills the storage space within the retention period, new logs cannot be written.

For access logs with large request bodies or response bodies, Neutree preserves readable body content as much as possible. When the body of a single log exceeds 12 MiB or part of the content cannot be read, the details and export results include only the prefix of the original body. Exported JSON, JSONL, and CSV records use body_truncated and body_incomplete to indicate the corresponding conditions.

Note

Requests for querying the list of available models are not written to access logs. For example, the OpenAI-compatible API GET /v1/models and the Anthropic-compatible API GET /anthropic/v1/models.

Viewing access logs

Prerequisites

• Access log storage has been configured and enabled for the control plane.
• The current user has the access log viewing permission for the corresponding workspace:
  • To view endpoint access logs, the user must have the Endpoint:Access Log Read permission.
  • To view external endpoint access logs, the user must have the External endpoint:Access Log Read permission.

Procedure

1. Log in to the Neutree management interface. In the left navigation pane, click Access Log.

2. Set filter conditions as needed. You can filter access logs by time, endpoint name, endpoint type, HTTP status code, model name, API key, and finish reason. The request count bar chart at the top of the page updates based on the selected time range. The table below displays access logs within the filter range and shows the following information: Time, Endpoint, App, Model, Status, API key, Tokens, Tok/s, Duration, and Finish. Hover over the status code in the Status column to view the description of the HTTP status code. When All workspaces is selected, the list also displays the Workspace column.

   Common values of Finish are as follows:

   Value	Description
   stop	The model normally ends generation, or encounters the stop sequence configured in the request.
   length	Generation stops after the generated content reaches the maximum number of tokens or the context length limit.
   tool_calls	The model stops the current response after returning a tool call request.
   content_filter	The generated content is truncated by the upstream content filtering policy.

3. In the access log list, click the target log to view request details. In addition to the information already displayed in the list, the details include Request model, Response model, Stream, Token prompt, and Token completion. For requests or responses that contain tool calls, tool results, images, or reasoning content, the details page displays detailed information about the corresponding Request body and Response body by content block.

Exporting access logs

To archive or analyze access logs offline, you can use the Neutree CLI to export access logs.

Preparation

Create an API key and store it securely.

Procedure

Run the following command:

neutree-cli-<arch> export access-log \
  -w [workspace] \
  --format [jsonl|json|csv] \
  --file [access-log.jsonl] \
  --since [YYYY-MM-DD] \
  --until [YYYY-MM-DD] \
  --limit [2000] \
  --api-key-id [api_key_id] \
  --server-url <server_url> \
  --api-key <api_key>

The parameters are described as follows:

Parameter	Description
[workspace]	Workspace name. If this optional parameter is left blank, the default workspace is used.
--all-workspaces or -A	Optional parameter. Exports access logs from all workspaces that the current API key has permission to read. This parameter cannot be used together with -w or --workspace.
[jsonl|json|csv]	Export format. This optional parameter can be set to jsonl, json, or csv. If not specified, the default format is jsonl.
[access-log.jsonl]	Export file path. If this optional parameter is left blank, the exported content is printed to standard output.
[YYYY-MM-DD]	Export time range. --since indicates the start date or time, and --until indicates the end date or time. If only a date is specified, --until includes all data from that day.
[2000]	Maximum number of records to export. By default, request bodies and response bodies are exported. If --limit is not explicitly set, a maximum of 2000 records are exported. Set --limit 0 to remove the record limit.
[api_key_id]	API key ID. This optional parameter filters access logs by API key.
<api_key>	The API key created during preparation. This API key must have the access log viewing permission.
<server_url>	Control plane access address, for example, http://localhost:3000.

You can also filter access logs by endpoint name, endpoint type, HTTP status code, model name, and finish reason:

neutree-cli-<arch> export access-log \
  --all-workspaces \
  --status 500 \
  --finish-reason tool_calls \
  --with-body=false \
  --format csv \
  --file failed-tool-calls.csv \
  --server-url <server_url> \
  --api-key <api_key>