Skip to content

Latest commit

 

History

History
316 lines (228 loc) · 5.66 KB

API.md

File metadata and controls

316 lines (228 loc) · 5.66 KB

LogScope API Documentation

This document describes the REST API endpoints available in LogScope.

Base URL

All API endpoints are relative to: http://localhost:8080/api

Authentication

Currently, LogScope does not require authentication for API access. AWS credentials are configured server-side.

Logs API

GET /logs

Retrieve cached log events with optional filtering.

Query Parameters:

Parameter Type Required Description
logGroup string No Filter by CloudWatch log group name
startTime long No Start timestamp in milliseconds
endTime long No End timestamp in milliseconds
level string No Filter by log level (ERROR, WARN, INFO, DEBUG)
search string No Full-text search query
limit int No Maximum results (default: 100, max: 1000)

Response:

[
  {
    "id": "abc123",
    "logGroupName": "/aws/lambda/my-function",
    "logStreamName": "2024/01/15/[$LATEST]abc123",
    "timestamp": 1705312800000,
    "message": "[INFO] Request processed successfully",
    "level": "INFO",
    "ingestionTime": 1705312801000
  }
]

GET /logs/stream

Server-Sent Events endpoint for real-time log streaming.

Query Parameters:

Parameter Type Required Description
logGroup string Yes CloudWatch log group to stream

Response: SSE stream of log events

POST /logs/sync

Trigger a sync from CloudWatch Logs to local cache.

Request Body:

{
  "logGroupName": "/aws/lambda/my-function",
  "startTime": 1705312800000,
  "endTime": 1705399200000
}

Response:

{
  "status": "syncing",
  "eventCount": 1523
}

GET /logs/groups

List available CloudWatch log groups.

Response:

[
  {
    "name": "/aws/lambda/my-function",
    "arn": "arn:aws:logs:us-east-1:123456789:log-group:/aws/lambda/my-function",
    "storedBytes": 1048576
  }
]

Patterns API

GET /patterns

Retrieve detected log patterns.

Query Parameters:

Parameter Type Required Description
logGroup string No Filter by log group
type string No Pattern type (ERROR, EXCEPTION, TIMEOUT, CUSTOM)
minOccurrences int No Minimum occurrence count

Response:

[
  {
    "id": "pattern-123",
    "pattern": "Connection refused to host: .*",
    "type": "ERROR",
    "occurrenceCount": 42,
    "firstSeen": 1705312800000,
    "lastSeen": 1705399200000,
    "sampleMessages": [
      "Connection refused to host: db-primary.internal"
    ]
  }
]

GET /patterns/{id}

Get details for a specific pattern.

Response:

{
  "id": "pattern-123",
  "pattern": "Connection refused to host: .*",
  "type": "ERROR",
  "occurrenceCount": 42,
  "firstSeen": 1705312800000,
  "lastSeen": 1705399200000,
  "sampleMessages": [
    "Connection refused to host: db-primary.internal",
    "Connection refused to host: cache-01.internal"
  ],
  "associatedLogGroups": [
    "/aws/lambda/api-handler",
    "/aws/lambda/worker"
  ]
}

POST /patterns/analyze

Trigger pattern analysis on cached logs.

Request Body:

{
  "logGroupName": "/aws/lambda/my-function",
  "startTime": 1705312800000,
  "endTime": 1705399200000
}

Response:

{
  "status": "analyzing",
  "patternsFound": 15
}

Alerts API

GET /alerts

List all alerts.

Query Parameters:

Parameter Type Required Description
status string No Filter by status (ACTIVE, ACKNOWLEDGED, RESOLVED)
severity string No Filter by severity (CRITICAL, HIGH, MEDIUM, LOW)
since long No Only alerts created after this timestamp

Response:

[
  {
    "id": "alert-456",
    "patternId": "pattern-123",
    "severity": "HIGH",
    "status": "ACTIVE",
    "message": "Error pattern exceeded threshold: 50 occurrences in 5 minutes",
    "createdAt": 1705399200000,
    "thresholdId": "threshold-789"
  }
]

GET /alerts/{id}

Get details for a specific alert.

PUT /alerts/{id}/acknowledge

Acknowledge an alert.

Request Body:

{
  "acknowledgedBy": "user@example.com",
  "notes": "Investigating the issue"
}

PUT /alerts/{id}/resolve

Resolve an alert.

Request Body:

{
  "resolvedBy": "user@example.com",
  "resolution": "Fixed database connection pool configuration"
}

GET /alerts/thresholds

List all configured alert thresholds.

POST /alerts/thresholds

Create a new alert threshold.

Request Body:

{
  "name": "High Error Rate",
  "patternType": "ERROR",
  "threshold": 50,
  "windowMinutes": 5,
  "severity": "HIGH",
  "notificationChannels": ["slack", "email"]
}

PUT /alerts/thresholds/{id}

Update an existing threshold.

DELETE /alerts/thresholds/{id}

Delete a threshold.

Error Responses

All endpoints return standard error responses:

{
  "code": 400,
  "message": "Invalid request: startTime must be before endTime"
}

Common HTTP Status Codes:

Code Description
200 Success
201 Created
400 Bad Request
404 Not Found
500 Internal Server Error
503 Service Unavailable (AWS connection issues)

Rate Limiting

The API does not currently implement rate limiting, but AWS API calls are subject to CloudWatch Logs service limits.

Pagination

For endpoints returning lists, use limit and offset parameters:

GET /api/logs?limit=100&offset=200

Response headers include pagination info:

X-Total-Count: 1523
X-Page-Size: 100
X-Page-Offset: 200