Papertrail入門

## はじめに
私自身がPapertrail入門するために最低限知っておきたい基本をおさえるために書きましたが、Papertrail入門する方の一助になれば幸いです。

## 目次
- [1. Papertrailの概要を理解する](#1-papertrailの概要を理解する)  
  - [1.1 ログ管理の基礎を知る](#11-ログ管理の基礎を知る)  
  - [1.2 Papertrailとは何か](#12-papertrailとは何か)  
- [2. Papertrailの基本](#2-papertrailの基本)  
  - [2.1 基本コンポーネント](#21-基本コンポーネント)  
    - [2.1.1 ログ送信元（Systems / Senders）](#211-ログ送信元systems--senders)  
    - [2.1.2 ロググループ（Log Groups）](#212-ロググループlog-groups)  
    - [2.1.3 Log Destinations](#213-log-destinations)  
  - [2.2 ログの送信](#22-ログの送信)  
  - [2.3 ログの検索とフィルタ](#23-ログの検索とフィルタ)  
    - [2.3.1 検索構文の基本](#231-検索構文の基本)  
      - [2.3.1.1 AND（暗黙の AND）](#2311-and暗黙の-and)  
      - [2.3.1.2 OR](#2312-or)  
      - [2.3.1.3 フレーズ検索](#2313-フレーズ検索)  
      - [2.3.1.4 丸括弧（優先順位）](#2314-丸括弧優先順位)  
      - [2.3.1.5 除外（Negation）](#2315-除外negation)  
      - [2.3.1.6 大文字・小文字](#2316-大文字小文字)  
      - [2.3.1.7 属性検索](#2317-属性検索)  
    - [2.3.2 時刻／日付検索](#232-時刻日付検索)  
    - [2.3.3 Click-to-Search](#233-click-to-search)  
- [3. Papertrailの応用機能を活用する](#3-papertrailの応用機能を活用する)  
  - [3.1 アラートと通知の設定](#31-アラートと通知の設定)  
  - [3.2 ログの長期保存](#32-ログの長期保存)  

## 1. Papertrailの概要を理解する

### 1.1 ログ管理の基礎を知る

* ログ管理とは、アプリケーションやシステムの動作記録（ログ）を一元的に収集し、検索・分析・アラートする仕組みです
* 以下はログの種類です

| ログの種類          | 内容                    | 例                                         | 用途                                                                   |
| -------------- | --------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
| アプリケーションログ     | アプリケーション内部の動作や状態      | 処理の開始・完了、エラーメッセージ、例外トレース、デバッグ情報など         | - 障害調査・デバッグ<br>- ユーザー操作の追跡（トラッキング）<br>- 業務ロジックの検証                    |
| アクセスログ         | ユーザーやクライアントからのリクエスト情報 | IPアドレス、URL、HTTPメソッド、ステータスコード、User-Agentなど | - 利用状況の把握<br>- セキュリティ監視（不正アクセス検出など）<br>- 負荷分析                        |
| システムログ         | OSやミドルウェア、デーモンの動作記録   | サービス起動・停止、カーネルメッセージ、ユーザー認証ログなど            | - システムの安定稼働の確認<br>- ハードウェアやOSレベルの障害調査<br>- セキュリティ監査（例：sudo実行、ログイン履歴） |
| セキュリティログ（監査ログ） | アクセス制御・認証・権限操作などの記録   | ログイン成功/失敗、パーミッション変更、ファイアウォールのログなど         | - コンプライアンス対応（SOC2、HIPAA、GDPRなど）<br>- 不正アクセス検出・追跡<br>- インシデント対応時の証拠保全 |
| データベースログ       | データベースのクエリ実行、接続状況、エラー | SQL実行、スロークエリ、接続失敗など                       | - パフォーマンスチューニング<br>- DB障害の調査<br>- アクセス監査                             |
| ネットワークログ       | 通信状況やネットワーク機器の動作ログ    | パケットの送受信、ポートアクセス、DNSリクエスト、VPN接続など         | - 通信障害の切り分け<br>- 不正な通信の検出<br>- ネットワーク構成の検証                           |

### 1.2 Papertrailとは何か

* **Papertrailの概要**

  * ログをリアルタイムで集約・閲覧・検索・アラートできる SaaS 型ロギングサービス
  * サーバー、アプリケーション、ネットワーク機器、Docker、Heroku などのログを一元管理可能

* **提供される主な機能**

  | 機能               | 説明                                     |
  | ---------------- | -------------------------------------- |
  | **リアルタイムログビューア** | ブラウザ上でライブログをリアルタイムに確認できる               |
  | **全文検索・フィルター**   | 正規表現、時刻範囲、ホスト、プログラム名などで柔軟に絞り込み         |
  | **アラート通知**       | 特定のログパターンでアラートを発報（Slack、Webhook、メール対応） |
  | **ロググループ管理**     | ログ送信元を用途別にグルーピング可能（例：本番環境・開発環境）        |
  | **ログの保存とアーカイブ**  | 保存期間はプランにより選択可能、S3や他サービスとの連携も可能        |

## 2. Papertrailの基本

### 2.1 基本コンポーネント

#### 2.1.1 ログ送信元（Systems / Senders）

* 各ログを生成・送信する場所
* 通常は「ホスト名（または識別名）」ごとに Papertrail に登録される
* 例：

  * `web01.example.com`（Linux サーバー）
  * `myapp-production`（Docker コンテナ）

#### 2.1.2 ロググループ（Log Groups）

* Papertrail 上で複数の送信元をまとめる論理的なグループ
* 典型的なグループ分類：

  * 環境別：`Production` / `Staging` / `Development`
  * サービス別：`Frontend` / `Backend` / `Batch Jobs`
  * リージョン別：`us-east1` / `eu-west`
  * 事業部・プロジェクト別：`E-commerce` / `Analytics`
* 利点：グループ単位でダッシュボード表示、検索、アラート設定が可能

#### 2.1.3 Log Destinations

* **概要**：Papertrail が受け取るログの入口
* **接続方式**：

  * Token（HTTPS）
  * Port（Syslog over UDP／TCP（平文 or TLS））
* **レート制限**：

  * UDP：パケットレート制限あり
  * TCP：秒間 10 コネクションまで
* **作成方法**：[Log Destinations の設定](https://www.papertrail.com/help/log-destinations/)
* **Tips**：

  * TCP＋TLS 送信を推奨（セキュリティと信頼性向上）
  * UDP 送信もサポートしているがデータ損失の可能性あり
  * ホスト名・ポートはダッシュボードの「Settings > Log Destinations」からコピー

### 2.2 ログの送信

* [Docker コンテナからの送信](https://www.papertrail.com/help/configuring-centralized-logging-from-docker/)
* アプリケーションからの直接送信（例：Node.js, Ruby など）
* Fluentd からの送信

  * `` `<match>` `` ブロックで `` `@type remote_syslog` `` を使い、Papertrail の syslog 受信サーバーへ転送
* その他の方法…

### 2.3 ログの検索とフィルタ

* Papertrail のイベントビューアはリアルタイムにログをストリーミングしつつ、検索ボックスにキーワードや条件を入力して絞り込めます
* 検索クエリは Google 風の簡易構文で記述可能で、複数ワードの AND/OR、フレーズ検索、正規表現などが使えます

#### 2.3.1 検索構文の基本

##### 2.3.1.1 AND（暗黙の AND）

```
something somethingelse
```

は

```
something AND somethingelse
```

##### 2.3.1.2 OR

```
something OR somethingelse
```

##### 2.3.1.3 フレーズ検索

```
"something else"
```

クオート内にクオートを含めたいときは、別の種類のクオートかバックスラッシュでエスケープします。

##### 2.3.1.4 丸括弧（優先順位）

```
something ("something else" OR "a third thing")
```

##### 2.3.1.5 除外（Negation）

```
-"exclude this"
something -("but not" OR "something else") "but this too"
```

##### 2.3.1.6 大文字・小文字

```
Completed in
```

は

```
completed in
```

##### 2.3.1.7 属性検索

* `sender`（送信元名）
* `program`（プログラム／ファイル名）
* `severity`（重要度）

#### 2.3.2 時刻／日付検索

* 検索ボックス横の時計アイコンから、ほぼどんなフォーマットの日付・時刻でも指定でき、イベントビューア上でリアルタイムに解釈・表示されます。

#### 2.3.3 Click-to-Search

- [**アカウント設定**](https://www.papertrailapp.com/account/settings)の[**「イベント ビューアー」タブに**](https://www.papertrailapp.com/account/viewer)アクセスして、クリック可能な利用可能な要素のリストを確認し、特定の要素を有効 (または無効) にします。
- [**クリック可能な要素（カスタム要素**](https://www.papertrail.com/help/viewer-click-to-search/#custom-clickable-elements)を含む）のリストは組織全体で共通ですが、**要素の有効化と無効化は自分のビューにのみ影響します**。そのため、同僚が望んでいない要素を有効にしてしまうのではないかと心配する必要はありません。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505972/142b9da5-da00-47a5-8ce8-5f4b8ee29664.png)

- イベントビューアでこれらの要素をクリックすると、その要素に一致する周囲のメッセージが表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505972/3ba2ae09-091f-43ea-a8f9-bd007ec98517.png)


- より詳細は[こちら](https://www.papertrail.com/help/event-viewer/)
- フィルターの適用
    - https://www.papertrail.com/help/log-filtering/

## 3. Papertrailの応用機能を活用する

### 3.1 アラートと通知の設定

- Papertrail のアラート機能は、保存済み検索（Saved Search）の条件にマッチしたログイベントを検出し、自動で通知を行う仕組みです
- 検出ルールの設定
    - イベントビューアで条件を入力し、🔍「Save Search」をクリック
    - 名前を付け、**Save & Setup an Alert** を選択
- 通知方法の選定（メール、Slack, Webhookなど）
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505972/8adcacea-eaf8-4f19-9cee-1cddb4c7b0de.png)
    
- アラートの条件、通知先の設定
    - **Frequency**
        - 1minute
        - 10minutes
        - 1hour
        - 1day
            - アラートに関連付けられたタイムゾーンの午前5時頃に送信されます
    - **Trigger when (選択した時間間隔内に一致するイベントがいくつ発生するしたら発火するか)**
        - at least {n} new events match
        - no new events match
            - イベントが発生していないことを検知したい時
    - **Send events with timestamps in**
        - タイムゾーンの選択

### 3.2 ログの長期保存

* **保存ポリシーの設定**：プランごとに保存期間を選択可能
* **Log Archivingの設定と活用**

  1. [自動S3アーカイブエクスポート設定](https://www.papertrail.com/help/automatic-s3-archive-export/)

     * **S3バケットの準備**：AWS管理コンソールで一意なバケット名を作成
     * **Papertrail側で有効化**：Settings → **Archives** → 「Enable automatic S3 archive」→ バケット名入力 → テストアップロードが走る → 完了後6～7時間で初回アーカイブ生成
  2. [ファイル構成](https://www.papertrail.com/help/permanent-log-archives/#downloading-multiple-archives)

     * **ファイル名例**： s3://バケット名/papertrail/logs/\<source\_id>/dt=YYYY-MM-DD/YYYY-MM-DD-HH.tsv.gz

     * **中身**：TSV＋gzip圧縮（1行ごとにログ1エントリ、タブ区切りで全10列）