Export and read logs

You enable access logs, review export locations, configure an export destination and query a controlled request.

Note: Balancer is in beta. Endpoints, fields and behavior may change before general availability, and the feature must be enabled on your account before use. Contact your NetActuate account manager to request access.

Prerequisites

• Balancer access and a key in the BALANCER_API_KEY environment variable with permission for these operations.
• The API host shown in the Balancer portal. Replace <your-api-host> in every example with that host.
• A shell, curl and Python 3 for examples that build JSON from environment variables.
• An HTTP group, permission to query logs, and a configured export destination with the required destination access. Location listing requires an account user with administrator access or a log export capability.

Resource identifiers come from your API responses. Set each variable when its value is available, before the first step that uses it.

Environment variable	Value
GROUP_ID	Returned resource identifier, or your selected scope identifier.
HTTP_LB_ID	Returned resource identifier, or your selected scope identifier.

For an identifier, enter the value returned for your resource and export it:

read -r -p 'GROUP_ID: ' GROUP_ID
export GROUP_ID

Steps

1. Enable access logs.

   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"accessLogsEnabled":true}'

   API reference: Update an HTTP group configuration

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

2. List available export locations.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/log-locations" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Returns the enabled log-export locations available for your account

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

3. Read your destination before editing it.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/log-export-destination" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Return your account log export destination

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

4. Enable the configured destination with the supported file format.

   curl --silent --show-error --include \
     --request PATCH \
     --url "https://<your-api-host>/log-export-destination" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"logExportDestination":{"enabled":true,"format":"jsonl","compression":"gzip"}}'

   API reference: Update your account log export destination

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200
   }

   TODO(verify): A complete initial destination setup with required storage fields and credential handling. This update assumes the destination is already configured.

5. Query a bounded window after sending a controlled request.

   curl --silent --show-error --include \
     --request POST \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/access-logs/query" \
     --header "x-api-key: $BALANCER_API_KEY" \
     --header "Content-Type: application/json" \
     --data-binary '{"timeRange":{"pastMinutes":5},"limit":100,"timezone":"UTC"}'

   API reference: Query managed access logs for an HTTP load balancer

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success"
   }

6. Read the final group setting.

   curl --silent --show-error --include \
     --request GET \
     --url "https://<your-api-host>/http-loadbalancers/$HTTP_LB_ID/groups/$GROUP_ID" \
     --header "x-api-key: $BALANCER_API_KEY"

   API reference: Get HTTP group

   Expected: HTTP 200. The following shows the response fields to check; additional data depends on your saved resources. Resource identifiers are illustrative.

   {
     "code": 200,
     "result": "success",
     "data": {
       "groupId": 1
     }
   }

Verify

Find the controlled request in the query result and at the destination. Compare its request identifier and UTC event time with the delivery time. Missing telemetry does not establish zero traffic, zero failures or no origin work.

Use your configured site domain in this traffic check:

curl --silent --show-error --include "https://example.com/"

Expected: the site behavior described above. The application response body and status depend on your origin and selected policies.

An API mutation saves desired configuration first. Readback and a live traffic check answer different questions. No fixed propagation time is established.

TODO(verify): Complete log retention, sampling and delivery retry guarantees.

Troubleshooting

Symptom	Cause	Fix
Location listing returns 401	Required account access or capability is missing	Ask an account administrator to inspect effective access.
Query has no expected event	Window or export setting differs, or delivery is pending	Check UTC times, accessLogsEnabled and destination readback.
Destination receives nothing	Destination availability or connectivity differs	Check the configured location and storage access.

Limits and defaults

Setting	Limit or default
Query limit	Default 100; 1 to 1000
Query timezone	Default UTC; maximum 64 characters
Query cursor	Maximum 4096 characters
Export format	jsonl
Compression	gzip
Group access logs	Disabled by default
Delivery latency	No fixed delivery deadline is established
Query time range	Maximum 525960 minutes

API status codes

Status	Meaning
200	Request succeeds; inspect returned data.
400	Invalid arguments or configuration.
401	Authentication or authorization denied.
404	Resource or parent is unavailable.
409	Resource state conflicts with the operation.
412	Inspect the returned error details.
500	The request encounters a server error.

Related API operations

• DELETE /log-export-destination
• GET /http-loadbalancers/{httpLbId}/groups/{groupId}
• GET /log-export-destination
• GET /log-locations
• PATCH /http-loadbalancers/{httpLbId}/groups/{groupId}
• PATCH /log-export-destination
• POST /http-loadbalancers/{httpLbId}/access-logs/query
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/access-logs/query
• POST /http-loadbalancers/{httpLbId}/groups/{groupId}/routes/{routeId}/access-logs/query
• PUT /log-export-destination

API reference

• Delete your account log export destination

• Get HTTP group

• Return your account log export destination

• Returns the enabled log-export locations available for your account

• Update an HTTP group configuration

• Update your account log export destination

• Query managed access logs for an HTTP load balancer

• Query managed access logs for an HTTP group

• Query managed access logs for an HTTP route

• Create or replace your account log export destination

• HTTP Load Balancers

• Groups and Routes

• Logs

Need Help?

Contact your account manager or use the Balancer portal.