# 日志记录

Queuety 会将每个作业和工作流事件记录到 `queuety_logs` 数据库表中。这里没有日志文件。所有条目都可通过 PHP API 和 CLI 查询。

## 事件类型

每条日志都有一个来自 `LogEvent` 枚举的事件类型：

| 事件 | 描述 |
|---|---|
| `started` | 作业开始执行 |
| `completed` | 作业成功完成 |
| `failed` | 一次尝试抛出异常，将会重试（最后一次尝试只记录 `buried`） |
| `buried` | 作业已用尽所有重试次数 |
| `retried` | 已安排重试作业 |
| `workflow_started` | 已分发工作流 |
| `workflow_completed` | 所有工作流步骤均已完成 |
| `workflow_failed` | 工作流步骤永久失败 |
| `workflow_paused` | 工作流已暂停 |
| `workflow_resumed` | 工作流已恢复 |
| `workflow_cancelled` | 工作流已取消 |
| `workflow_rewound` | 工作流已回退到较早的步骤 |
| `workflow_forked` | 工作流已分叉为新的工作流 |
| `workflow_deadline_exceeded` | 工作流错过了 `must_complete_within()` 截止时间 |
| `debug` | 调试级别消息（启用 `QUEUETY_DEBUG` 时） |

## 日志字段

每条日志包含：

| 字段 | 描述 |
|---|---|
| `id` | 自动递增 ID |
| `event` | 事件类型字符串 |
| `handler` | 处理器名称或类名 |
| `job_id` | 关联的作业 ID（可为 null） |
| `workflow_id` | 关联的工作流 ID（可为 null） |
| `step_index` | 工作流步骤索引（可为 null） |
| `attempt` | 尝试次数 |
| `duration_ms` | 执行时长（毫秒） |
| `error_message` | 失败时的错误消息 |
| `created_at` | 时间戳 |

## 通过 PHP 查询日志

```php
$logger = Queuety::logger();

// Logs for a specific job
$logs = $logger->for_job( 42 );

// Logs for a specific workflow
$logs = $logger->for_workflow( 7 );

// Logs for a specific handler
$logs = $logger->for_handler( 'send_email', 50 );

// Logs for a specific event type
$logs = $logger->for_event( \Queuety\Enums\LogEvent::Failed, 50 );

// Logs since a datetime
$logs = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
```

## 通过 CLI 查询日志

```bash
# Recent logs (last 24 hours)
wp queuety log

# Logs for a specific job
wp queuety log --job=42

# Logs for a specific workflow
wp queuety log --workflow=7

# Logs for a handler
wp queuety log --handler=send_email

# Logs for an event type
wp queuety log --event=failed

# Logs since a datetime
wp queuety log --since="2025-01-01 00:00:00"

# Custom limit and format
wp queuety log --limit=100 --format=json
```

## 日志保留

日志会一直保留，直到你清除它们。`QUEUETY_LOG_RETENTION_DAYS` 常量会被 `Config::log_retention_days()` 读取，但目前没有任何功能使用它，因此它不会清除任何内容（[#15](https://github.com/inline0/queuety/issues/15)）。`wp queuety log purge` 子命令也无法调用（[#11](https://github.com/inline0/queuety/issues/11)）。

从 PHP 清除，例如通过你自己的计划任务或使用 `wp eval`：

```php
$count = Queuety::logger()->purge( 30 );
```