# 바로 작업이 실패하는 순간.

> 백그라운드 작업이나 워커가 실패하면 푸시 알림으로 바로 알려드려요. Pocket Alert를 Sidekiq, Celery, Laravel 큐, BullMQ에 연결하면 워커 실패 알림이 휴대폰으로 빠르게 도착해요.

<!-- source: https://pocketalert.app/ko/use-cases/background-job-alerts -->

마지막 업데이트: 2026-08-11

Sidekiq, Celery, Laravel, BullMQ의 작업 실패 훅에서 Pocket Alert를 호출하세요. 워커에서 예외가 발생하면 작업 이름, 인자, 예외 내용이 휴대폰으로 전달되고, 중요한 작업이 끝나면 완료 알림도 도착합니다.

## 백그라운드 작업 알림 설정 3단계

1. **API 키 발급 또는 CLI 설치** — API 키를 만들거나, 셸 기반 워커라면 Pocket Alert CLI를 설치하세요.
2. **실패 훅에 연결** — 큐 프레임워크의 실패 훅에서 작업 이름과 오류를 넘겨 Pocket Alert를 호출하세요.
3. **죽은 워커 잡아내기** — 실패하는 작업을 실행해 보세요. 어느 워커가 왜 죽었는지 휴대폰이 바로 울립니다.

## 죽은 워커를 놓치지 마세요

조용히 죽은 워커는 작업 전체를 함께 멈추게 합니다. 작업에서 예외가 발생하면 바로 알려드립니다.

- **모든 큐와 연동** — Sidekiq, Celery, Laravel, BullMQ, Hangfire에서 이미 사용 중인 실패 훅으로 Pocket Alert를 호출하세요.
- **실패 시 알림** — death 핸들러에 연결하면 실패한 작업만 알려드립니다.
- **전체 실패 맥락** — 작업 클래스, 인자, 예외가 메시지에 담겨 와서 트래커를 열지 않고도 원인을 파악할 수 있습니다.
- **실행 확인** — 중요한 작업은 완료 시 알림을 받으세요. 야간 가져오기 알림이 없다면 실행이 멈춘 것입니다.
- **워커별 채널** — 워커마다 애플리케이션을 따로 만들면 멈춘 큐를 한눈에 찾을 수 있습니다.
- **발생 즉시 알림** — 워커에서 예외가 발생하면 로그를 확인하기 전에 휴대폰으로 바로 알림이 옵니다.

## 작업 핸들러에서 바로 알림 보내기

### Laravel 큐 — failed() 훅

```
public function failed(Throwable $e): void
{
    Http::withHeaders(['Token' => 'YOUR_API_KEY'])
        ->post('https://api.pocketalert.app/v1/messages', [
            'title' => 'Job failed: ' . class_basename($this),
            'message' => $e->getMessage(),
            'level' => 'critical',
        ]);
}
```

### Sidekiq — death 핸들러

`config/initializers/sidekiq.rb`에서 재시도 횟수를 모두 소진하면 실행되도록 설정하세요:

```
Sidekiq.configure_server do |config|
  config.death_handlers << ->(job, ex) do
    Net::HTTP.post(
      URI('https://api.pocketalert.app/v1/messages'),
      { title: "Job died: #{job['class']}",
        message: "jid #{job['jid']}: #{ex.message}" }.to_json,
      'Token' => 'YOUR_API_KEY', 'Content-Type' => 'application/json')
  end
end
```

### Celery — task_failure 시그널

```
import requests
from celery.signals import task_failure

@task_failure.connect
def notify_failure(sender=None, task_id=None, exception=None, **kw):
    requests.post(
        'https://api.pocketalert.app/v1/messages',
        headers={'Token': 'YOUR_API_KEY'},
        json={'title': f'Task failed: {sender.name}',
              'message': f'{task_id}: {exception}'})
```

### BullMQ — 워커 failed 이벤트

```
worker.on('failed', async (job, err) => {
  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { 'Token': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: `Job failed: ${job?.name}`,
      message: `${job?.id}: ${err.message}`,
    }),
  });
});
```

특정 애플리케이션이나 기기를 지정하는 방법은 [문서](https://info.pocketalert.app/getting-started.html)에서 확인하세요.

## 자주 묻는 질문

### 백그라운드 작업 실패 시 알림은 어떻게 받나요?

작업의 실패 핸들러나 rescue 블록에서 Pocket Alert API 또는 CLI를 호출하세요. 워커에서 예외가 발생하면 작업 이름과 오류 내용이 담긴 푸시 알림이 휴대폰으로 전송됩니다.

### 큐 프레임워크에 연동할 수 있나요?

네. 대부분의 큐 프레임워크는 실패 콜백을 제공합니다. Sidekiq death 핸들러, Celery task_failure, Laravel failed()가 그렇습니다. 여기에 Pocket Alert 호출을 넣으면 실제 실패일 때만 알림을 받습니다.

### 작업 이름과 오류도 포함할 수 있나요?

본문에 작업 클래스, 인자, 예외 메시지를 넣으세요. 알림만 봐도 어떤 작업이 왜 실패했는지 알 수 있어서, 보통 에러 트래커를 열어볼 필요가 없습니다.

### 어떤 큐 시스템을 지원하나요?

Sidekiq, Resque, Celery, RQ, Laravel 큐, BullMQ, Hangfire, Kubernetes Jobs 모두 실패 훅 또는 0이 아닌 종료 코드를 통해 연동됩니다.

### 작업이 실제로 실행되었는지 확인할 수 있나요?

중요한 작업에는 완료 알림을 보내세요. 야간 가져오기 작업의 알림이 오지 않는다면, 워커가 아무 오류 없이 처리를 멈춘 것일 가능성이 큽니다.

### 워커 장애 알림이 방해 금지 모드를 무시할 수 있나요?

네. 실패 훅에서 level=critical을 전달하면 Android는 방해 금지 모드를 우회하는 채널로 푸시를 보내고, iPhone은 집중 모드를 뚫고 나오는 시간 민감 알림으로 전달합니다. 일상적인 작업의 완료 알림은 level=silent를 사용해 소리 없이 기록으로만 남길 수 있습니다.
