日志管理API

日志管理API提供对系统各类日志的查询、搜索、过滤、分析和导出功能，支持多源日志的统一管理。

1. 基础路径

所有日志管理API的基础路径为：/api/v1/logs

2. 认证方式

所有日志管理API需要通过JWT Token或API Key认证。

请求头：

JWT Token: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
或API Key: Authorization: ApiKey ak_1234567890abcdef1234567890abcdef12345678

3. 日志查询接口

3.1 日志搜索

请求URL：/api/v1/logs/search

请求方法：POST

请求体：

{
  "query": "error OR exception",
  "filters": [
    {
      "field": "source",
      "values": ["application", "system"]
    },
    {
      "field": "level",
      "values": ["ERROR", "FATAL"]
    },
    {
      "field": "host",
      "values": ["server-1", "server-2"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "page": 1,
  "page_size": 50,
  "sort_by": "timestamp",
  "sort_order": "desc"
}

参数说明：

query：全文搜索关键词，支持逻辑运算符（AND/OR/NOT）和通配符
filters：字段过滤条件，可选
- field：字段名称
- values：字段值列表
time_range：时间范围，必填
- start：开始时间
- end：结束时间
page：页码，可选，默认1
page_size：每页数量，可选，默认50，最大1000
sort_by：排序字段，可选，默认timestamp
sort_order：排序方向，可选（asc/desc），默认desc

响应示例：

{
  "success": true,
  "code": 200,
  "message": "搜索成功",
  "data": {
    "total": 1250,
    "page": 1,
    "page_size": 50,
    "logs": [
      {
        "id": "1",
        "timestamp": "2023-05-01T15:30:45Z",
        "level": "ERROR",
        "source": "application",
        "host": "server-1",
        "service": "api-gateway",
        "message": "Database connection error: Connection refused",
        "fields": {
          "error_code": 5001,
          "trace_id": "abc-123-def-456",
          "user_id": "1001",
          "ip": "192.168.1.100"
        }
      },
      {
        "id": "2",
        "timestamp": "2023-05-01T15:29:30Z",
        "level": "FATAL",
        "source": "system",
        "host": "server-2",
        "service": "database",
        "message": "Fatal disk error on database server",
        "fields": {
          "disk": "/dev/sdb",
          "error_code": "IO_ERROR_001",
          "process_id": 12345
        }
      },
      ...
    ]
  }
}

3.2 获取日志详情

请求URL：/api/v1/logs/{log_id}

请求方法：GET

路径参数：

log_id：日志ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "id": "1",
    "timestamp": "2023-05-01T15:30:45Z",
    "level": "ERROR",
    "source": "application",
    "host": "server-1",
    "service": "api-gateway",
    "message": "Database connection error: Connection refused",
    "raw": "2023-05-01T15:30:45Z [ERROR] [api-gateway] [server-1] Database connection error: Connection refused {\"error_code\": 5001, \"trace_id\": \"abc-123-def-456\", \"user_id\": \"1001\", \"ip\": \"192.168.1.100\"}",
    "fields": {
      "error_code": 5001,
      "trace_id": "abc-123-def-456",
      "user_id": "1001",
      "ip": "192.168.1.100",
      "thread_id": "main-123",
      "file": "DatabaseConnector.java",
      "line": 45,
      "stack_trace": "java.sql.SQLException: Connection refused\n  at com.example.DatabaseConnector.connect(DatabaseConnector.java:45)\n  ..."
    },
    "related_logs": [
      {
        "id": "3",
        "timestamp": "2023-05-01T15:30:40Z",
        "level": "INFO",
        "message": "Attempting to connect to database",
        "trace_id": "abc-123-def-456"
      }
    ]
  }
}

3.3 搜索日志上下文

请求URL：/api/v1/logs/{log_id}/context

请求方法：GET

路径参数：

log_id：日志ID，必填

请求参数：

before：前后各返回多少条日志，可选，默认10
after：前后各返回多少条日志，可选，默认10
same_trace：是否只返回相同trace_id的日志，可选，默认false

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "target_log": {
      "id": "1",
      "timestamp": "2023-05-01T15:30:45Z",
      "level": "ERROR",
      "message": "Database connection error: Connection refused"
    },
    "before_logs": [
      {
        "id": "3",
        "timestamp": "2023-05-01T15:30:40Z",
        "level": "INFO",
        "message": "Attempting to connect to database"
      },
      {
        "id": "4",
        "timestamp": "2023-05-01T15:30:41Z",
        "level": "DEBUG",
        "message": "Preparing connection parameters"
      }
    ],
    "after_logs": [
      {
        "id": "5",
        "timestamp": "2023-05-01T15:30:46Z",
        "level": "WARN",
        "message": "Connection retry scheduled in 5 seconds"
      },
      {
        "id": "6",
        "timestamp": "2023-05-01T15:30:51Z",
        "level": "INFO",
        "message": "Retrying database connection"
      }
    ]
  }
}

4. 日志聚合与分析接口

4.1 日志聚合统计

请求URL：/api/v1/logs/aggregate

请求方法：POST

请求体：

{
  "query": "error",
  "filters": [
    {
      "field": "source",
      "values": ["application"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "group_by": ["level", "service"],
  "aggregations": [
    {
      "type": "count",
      "alias": "total"
    }
  ],
  "limit": 100
}

参数说明：

query：全文搜索关键词，可选
filters：字段过滤条件，可选
time_range：时间范围，必填
group_by：分组字段列表，必填
aggregations：聚合操作列表，必填
- type：聚合类型（count, sum, avg, min, max等）
- field：聚合字段（对于sum, avg等需要）
- alias：聚合结果别名
limit：返回结果数量限制，可选，默认100

响应示例：

{
  "success": true,
  "code": 200,
  "message": "聚合成功",
  "data": {
    "aggregations": [
      {
        "key": {"level": "ERROR", "service": "api-gateway"},
        "count": 125
      },
      {
        "key": {"level": "ERROR", "service": "user-service"},
        "count": 89
      },
      {
        "key": {"level": "WARN", "service": "api-gateway"},
        "count": 342
      },
      {
        "key": {"level": "WARN", "service": "order-service"},
        "count": 231
      }
    ]
  }
}

4.2 日志时序分析

请求URL：/api/v1/logs/timeseries

请求方法：POST

请求体：

{
  "query": "error OR exception",
  "filters": [
    {
      "field": "level",
      "values": ["ERROR", "FATAL"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "interval": "15m",
  "group_by": ["level"]
}

参数说明：

query：全文搜索关键词，可选
filters：字段过滤条件，可选
time_range：时间范围，必填
interval：时间间隔，必填（如1m, 5m, 15m, 1h, 1d）
group_by：分组字段列表，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "时序分析成功",
  "data": {
    "interval": "15m",
    "time_series": [
      {
        "key": {"level": "ERROR"},
        "values": [
          {"time": "2023-05-01T00:00:00Z", "count": 12},
          {"time": "2023-05-01T00:15:00Z", "count": 8},
          {"time": "2023-05-01T00:30:00Z", "count": 15},
          ...
        ]
      },
      {
        "key": {"level": "FATAL"},
        "values": [
          {"time": "2023-05-01T00:00:00Z", "count": 1},
          {"time": "2023-05-01T00:15:00Z", "count": 0},
          {"time": "2023-05-01T00:30:00Z", "count": 2},
          ...
        ]
      }
    ]
  }
}

4.3 日志关键字分析

请求URL：/api/v1/logs/keywords

请求方法：POST

请求体：

{
  "query": "error",
  "filters": [
    {
      "field": "level",
      "values": ["ERROR", "FATAL"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "field": "message",
  "limit": 20,
  "min_count": 5
}

参数说明：

query：全文搜索关键词，可选
filters：字段过滤条件，可选
time_range：时间范围，必填
field：要提取关键字的字段，可选，默认message
limit：返回关键字数量限制，可选，默认20
min_count：最小出现次数，可选，默认5

响应示例：

{
  "success": true,
  "code": 200,
  "message": "关键字分析成功",
  "data": {
    "keywords": [
      {"word": "connection", "count": 156},
      {"word": "error", "count": 342},
      {"word": "database", "count": 123},
      {"word": "timeout", "count": 89},
      {"word": "exception", "count": 201},
      {"word": "refused", "count": 67},
      ...
    ]
  }
}

4.4 日志异常检测

请求URL：/api/v1/logs/anomalies

请求方法：POST

请求体：

{
  "filters": [
    {
      "field": "service",
      "values": ["payment-service"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "algorithm": "statistical",
  "window_size": "1h",
  "sensitivity": "medium",
  "detect_types": ["volume", "pattern", "level_change"]
}

参数说明：

filters：字段过滤条件，可选
time_range：时间范围，必填
algorithm：异常检测算法，可选（statistical、machine_learning、rule_based）
window_size：检测窗口大小，可选，默认"1h"
sensitivity：检测灵敏度，可选（low、medium、high）
detect_types：检测类型，可选（volume、pattern、level_change）

响应示例：

{
  "success": true,
  "code": 200,
  "message": "异常检测成功",
  "data": {
    "anomalies": [
      {
        "timestamp": "2023-05-01T14:30:00Z",
        "type": "volume",
        "severity": "high",
        "description": "日志量突增",
        "details": {
          "expected": 120,
          "actual": 540,
          "increase_rate": 350
        },
        "related_logs": [
          {
            "id": "100",
            "timestamp": "2023-05-01T14:30:00Z",
            "level": "ERROR",
            "message": "Payment gateway timeout"
          }
        ]
      },
      {
        "timestamp": "2023-05-01T18:45:00Z",
        "type": "pattern",
        "severity": "medium",
        "description": "出现新的错误模式",
        "details": {
          "pattern": "Transaction failed: insufficient funds",
          "count": 35
        }
      }
    ]
  }
}

5. 日志源与管理接口

5.1 获取日志源列表

请求URL：/api/v1/logs/sources

请求方法：GET

请求参数：

page：页码，默认1
page_size：每页数量，默认20
name：日志源名称搜索，可选
type：日志源类型筛选，可选（file、syslog、http、container、database等）
status：状态筛选，可选（active、inactive、error）

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 35,
    "page": 1,
    "page_size": 20,
    "sources": [
      {
        "id": "1",
        "name": "application-logs",
        "type": "file",
        "path": "/var/log/app/*.log",
        "host_pattern": "server-*",
        "status": "active",
        "last_collected": "2023-05-01T23:59:59Z",
        "log_count": 125000,
        "created_at": "2023-01-01T00:00:00Z"
      },
      {
        "id": "2",
        "name": "system-logs",
        "type": "file",
        "path": "/var/log/syslog",
        "host_pattern": "server-*",
        "status": "active",
        "last_collected": "2023-05-01T23:59:59Z",
        "log_count": 234000,
        "created_at": "2023-01-01T00:00:00Z"
      },
      ...
    ]
  }
}

5.2 创建日志源

请求URL：/api/v1/logs/sources

请求方法：POST

请求体：

{
  "name": "new-service-logs",
  "type": "file",
  "description": "新服务日志",
  "config": {
    "path": "/var/log/new-service/*.log",
    "host_pattern": "server-*",
    "encoding": "utf-8",
    "parser": {
      "type": "grok",
      "pattern": "%{TIMESTAMP_ISO8601:timestamp} \[%{LOGLEVEL:level}\] \[%{DATA:service}\] %{GREEDYDATA:message}"
    }
  },
  "tags": {
    "service": "new-service",
    "environment": "production"
  },
  "retention_days": 30,
  "enabled": true
}

参数说明：

name：日志源名称，必填
type：日志源类型，必填
description：描述，可选
config：配置信息，必填，根据类型不同而不同
tags：标签，可选
retention_days：保留天数，可选
enabled：是否启用，可选，默认true

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志源创建成功",
  "data": {
    "id": "36",
    "name": "new-service-logs",
    "type": "file",
    "status": "active",
    "created_at": "2023-05-02T00:00:00Z"
  }
}

5.3 更新日志源

请求URL：/api/v1/logs/sources/{source_id}

请求方法：PUT

路径参数：

source_id：日志源ID，必填

请求体：

{
  "name": "updated-service-logs",
  "description": "更新后的服务日志",
  "config": {
    "path": "/var/log/new-service/*.log",
    "encoding": "utf-8",
    "parser": {
      "type": "grok",
      "pattern": "%{TIMESTAMP_ISO8601:timestamp} \[%{LOGLEVEL:level}\] \[%{DATA:service}\] \[%{DATA:trace_id}\] %{GREEDYDATA:message}"
    }
  },
  "tags": {
    "service": "new-service",
    "environment": "production",
    "version": "1.2.0"
  },
  "retention_days": 60,
  "enabled": true
}

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志源更新成功",
  "data": {
    "id": "36",
    "name": "updated-service-logs",
    "status": "active",
    "updated_at": "2023-05-02T01:00:00Z"
  }
}

5.4 删除日志源

请求URL：/api/v1/logs/sources/{source_id}

请求方法：DELETE

路径参数：

source_id：日志源ID，必填

请求体：

{
  "delete_logs": false
}

参数说明：

delete_logs：是否同时删除该日志源的历史日志，可选，默认false

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志源删除成功",
  "data": {
    "deleted_source": "updated-service-logs",
    "delete_logs": false
  }
}

6. 日志写入与导入接口

6.1 写入单条日志

请求URL：/api/v1/logs/write

请求方法：POST

请求体：

{
  "timestamp": "2023-05-02T10:00:00Z",
  "level": "INFO",
  "source": "application",
  "host": "api-server-1",
  "service": "custom-service",
  "message": "Custom log message from API",
  "fields": {
    "request_id": "req-123-456",
    "user_id": "789",
    "action": "create",
    "duration_ms": 123
  }
}

参数说明：

timestamp：时间戳，可选，默认为当前时间
level：日志级别，可选
source：日志源，可选
host：主机名，可选
service：服务名，可选
message：日志消息，必填
fields：额外字段，可选

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志写入成功",
  "data": {
    "log_id": "1001",
    "timestamp": "2023-05-02T10:00:00Z"
  }
}

6.2 批量写入日志

请求URL：/api/v1/logs/batch-write

请求方法：POST

请求体：

{
  "logs": [
    {
      "timestamp": "2023-05-02T10:00:00Z",
      "level": "INFO",
      "source": "application",
      "host": "api-server-1",
      "service": "custom-service",
      "message": "First custom log message",
      "fields": {
        "request_id": "req-123-456",
        "user_id": "789"
      }
    },
    {
      "timestamp": "2023-05-02T10:00:01Z",
      "level": "WARN",
      "source": "application",
      "host": "api-server-1",
      "service": "custom-service",
      "message": "Second custom log message",
      "fields": {
        "request_id": "req-123-457",
        "user_id": "890"
      }
    }
  ]
}

响应示例：

{
  "success": true,
  "code": 200,
  "message": "批量日志写入成功",
  "data": {
    "written_count": 2,
    "failed_count": 0,
    "log_ids": ["1001", "1002"]
  }
}

6.3 导入日志文件

请求URL：/api/v1/logs/import

请求方法：POST

请求体：multipart/form-data

file：日志文件，必填
source_id：日志源ID，可选
parser_config：解析器配置，可选，JSON字符串
tags：标签，可选，JSON字符串

示例请求（curl）：

curl -X POST "http://api.example.com/api/v1/logs/import" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "file=@application.log" \
  -F "parser_config={\"type\":\"json\"}" \
  -F "tags={\"environment\":\"test\"}"

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志文件导入成功",
  "data": {
    "import_id": "import-123-456",
    "filename": "application.log",
    "file_size": 1048576,
    "logs_count": 5000,
    "status": "processing"
  }
}

7. 日志导出接口

7.1 导出日志

请求URL：/api/v1/logs/export

请求方法：POST

请求体：

{
  "query": "error OR exception",
  "filters": [
    {
      "field": "level",
      "values": ["ERROR", "FATAL"]
    }
  ],
  "time_range": {
    "start": "2023-05-01T00:00:00Z",
    "end": "2023-05-01T23:59:59Z"
  },
  "format": "json",
  "fields": ["timestamp", "level", "host", "service", "message", "fields"],
  "max_logs": 10000
}

参数说明：

query：全文搜索关键词，可选
filters：字段过滤条件，可选
time_range：时间范围，必填
format：导出格式，可选（json、csv、text），默认json
fields：包含的字段列表，可选
max_logs：最大导出日志条数，可选，默认10000

响应示例：

{
  "success": true,
  "code": 200,
  "message": "日志导出任务创建成功",
  "data": {
    "export_id": "export-123-456",
    "status": "processing",
    "download_url": null,
    "estimated_completion": "2023-05-02T11:05:00Z"
  }
}

7.2 查询导出状态

请求URL：/api/v1/logs/export/{export_id}

请求方法：GET

路径参数：

export_id：导出任务ID，必填

响应示例：

{
  "success": true,
  "code": 200,
  "message": "查询成功",
  "data": {
    "export_id": "export-123-456",
    "status": "completed",
    "download_url": "https://api.example.com/downloads/export-123-456.json",
    "file_size": 5242880,
    "logs_count": 8500,
    "created_at": "2023-05-02T11:00:00Z",
    "completed_at": "2023-05-02T11:03:45Z",
    "expires_at": "2023-05-09T11:03:45Z"
  }
}