Access Usage Logs

This guide walks you through querying usage logs to retrieve detailed operational metrics from your service instances.

Prerequisites

A Vidos account with appropriate permissions
An API key with access to the logs management API
At least one service instance deployed

Understanding usage logs

Usage logs capture detailed metrics about individual service instance operations. Each log entry includes:

HTTP request and response details
Authentication method and context
Timestamp and duration
Service instance identifier
Request/response headers and body content

Usage logs are scoped to specific instances, allowing you to monitor individual deployments independently.

Query usage logs for an instance

Usage logs use an asynchronous query model. You initiate a query and then poll for results:

Step 1: Initiate a query

Send a POST request to initiate a usage log query for a specific service instance:

curl -X POST https://logs.management.eu.vidos.id/resolver/my-resolver-instance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z",
    "method": "POST"
  }'

Request parameters:

from (required): ISO 8601 start date-time for the query window
to (required): ISO 8601 end date-time for the query window
method (optional): Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)
service (URL parameter): The service name (authorizer, resolver, validator, verifier, etc.)
instanceResourceId (URL parameter): Your instance’s resource identifier

Response:

{
    "queryExecutionId": "abc-123-def-456"
}

Store the queryExecutionId to retrieve results.

Step 2: Poll for results

Use the query execution ID to retrieve results:

curl -X GET https://logs.management.eu.vidos.id/resolver/my-resolver-instance/query-result/abc-123-def-456 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
    "data": [
        {
            "account_id": "acc_12345",
            "service": "resolver",
            "instance_id": "my-resolver-instance",
            "metadata": {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "requestId": "req_abc123",
                "version": "1.0",
                "region": "eu",
                "scope": "service"
            },
            "request": {
                "method": "POST",
                "path": "/api/resolve",
                "auth": {
                    "method": "api-key",
                    "publicKey": "pk_abc123"
                }
            },
            "response": {
                "statusCode": 200,
                "headers": {}
            },
            "timestamp": 1704067200000
        }
    ],
    "nextToken": "next_page_token"
}

Step 3: Handle pagination

If your result set is large, use the nextToken to retrieve the next page:

curl -X GET "https://logs.management.eu.vidos.id/resolver/my-resolver-instance/query-result/abc-123-def-456?nextToken=next_page_token" \
  -H "Authorization: Bearer YOUR_API_KEY"

Continue polling until nextToken is not returned, indicating you’ve reached the end of results.

Common usage patterns

Query all requests in the past 24 hours

Monitor recent activity on your instance:

FROM=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)
TO=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST https://logs.management.eu.vidos.id/resolver/my-resolver-instance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"$FROM\",
    \"to\": \"$TO\"
  }"

Find failed requests

Query for requests that returned error status codes by retrieving all requests, then filtering the response:

curl -X POST https://logs.management.eu.vidos.id/resolver/my-resolver-instance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z"
  }' | jq '.data[] | select(.response.statusCode >= 400)'

Monitor POST requests only

Filter by specific HTTP method:

curl -X POST https://logs.management.eu.vidos.id/resolver/my-resolver-instance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-02T00:00:00Z",
    "method": "POST"
  }'

Verify your query

You have successfully queried usage logs when:

HTTP status is 201 for initiation or 200 for results retrieval
queryExecutionId is returned from the initiation request
data array contains log entries with expected timestamps
Each log entry includes request, response, and metadata fields

Troubleshooting

Issue	Solution
”Instance not found” error	Verify the service name and instance resource ID are correct
Empty `data` array	No requests occurred during the specified time window
Query timeout	Try with a smaller time range or use pagination with `nextToken`
”Unauthorized” error	Verify your API key is valid and has access to the logs API
”Invalid time range” error	Ensure `from` is before `to` in ISO 8601 format

Understanding Usage Logs: Conceptual overview
Usage Logs API Reference: Complete API documentation
Create an Instance: Set up your first instance
Create API Key: Generate authentication credentials