【入門編】Sentryの「Integration Platform」を活用して独自のInternal Integrationsを開発する手順 – 運用監視・オブザーバビリティ活用バイブル

こんにちは！Sentryを日々の開発や運用で使い倒しているかい？
エラーが発生したときにメールが飛んできたり、Slackに通知が来たりするアレだ。非常に便利なんだけど、現場で長く運用していると「自社の特殊な社内チャットツールに飛ばしたい」「エラートラッキングと同時に、社内のインシデント管理DBへ自動でチケットを起票したい」といった、ちょっとした“わがまま”が出てくるものなんだよね。

そんなとき、OAuthの面倒な認可フローをすっ飛ばして、サクッと爆速でSentryと自社システムを直結できる神機能が「Internal Integrations（内部インテグレーション）」だ。

今回は、このInternal Integrationsの作り方を、初心者でも迷わないように優しく、かつ現場で即座に使えるレベルまで徹底的に解説していくよ。これをマスターすれば、毎日のエラー対応のフローが劇的にスムーズになりますよ。一緒に手を動かしていこう！

—

1. Sentryの「Internal Integrations」とは何者か？

まず大前提として、Sentryの拡張機能には「Public Integration（一般公開用）」と「Internal Integration（社内・個人用）」の2種類がある。

  • Public Integration: SentryのApp Store（Integrations Directory）で世界中に公開するためのもの。OAuth 2.0の認可コードフローが必要で、審査もある。
  • Internal Integration: 「社内専用」の特権モード。OAuthの面倒な実装が一切不要。ボタンをポチポチッと押すだけで即座にAPIトークンが発行され、SentryのWebhookを受け取ったり、SentryのAPIを叩いたりできる。

要するに、「社内ニート向け（失礼、社内ニッチ向け）の自動化スクリプトやチャット連携を、3分で作るためのチート機能」だと思ってくれていい。

—

2. 基礎セットアップ：Internal Integrationの作成手順

百聞は一見に如かず。まずはSentryの管理画面で、あなた専用の連携チャネル（Internal Integration）を作ってみよう。

ステップ1：設定画面への扉を開く

1. Sentryの組織（Organization）のダッシュボードにログインする。
2. 左下の自分のアイコン、または組織名をクリックして [Settings]（設定） に移動する。
3. サイドメニューの下部にある [Integrations] をクリック。
4. 右上あたりにある [Develop Intergration] というリンク（またはボタン）を押す。
5. さらに [Create Internal Integration] を選択だ。

ステップ2：権限（Scopes）の設定

ここが一番重要。このIntegrationに「何を許可するか」を定義する。今回は「エラーを受け取って、コンソールに出力する（あるいは独自チャットに送る）」という基本のHelloWorldを想定して、以下の権限を与えよう。

  • Project: `Read & Write` （プロジェクト情報の読み書き。エラーを検知するため）
  • Organization: `Read` （組織情報の読み取り）
  • Issue & Event: `Read & Write` （エラーイベントの詳細を取得・更新するため）

ステップ3：Webhook URLの設定とトークン発行

  • Webhook URL: 後で作る自作の受信サーバー（今回はローカル環境の`http://localhost:3000/webhook`など）のURLを指定する。
  • 保存（Save）を押すと、画面の下部に `Token` が発行される。これが君のマスターキーだ。絶対に外部に漏らさないように、環境変数として安全に管理しよう。

—

3. 精度高いHelloWorld：Webhookを受け取るサーバーの実装

さて、Sentry側の準備は整った。次は、Sentryでエラーが発生したときに、それをキャッチする受信サーバーを作ろう。
今回は、最もシンプルで分かりやすい Node.js (Express) を使うよ。

まずはプロジェクトフォルダを作って、必要なパッケージをインストールしよう。

mkdir sentry-internal-bot
cd sentry-internal-bot
npm init -y
npm install express body-parser

そしたら、以下のコードを `server.js` という名前で保存してほしい。これが今回のHelloWorldの心臓部だ。

`server.js` の実装

const express = require(‘express’);
const bodyParser = require(‘body-parser’);

const app = express();
const PORT = process.env.PORT || 3000;

// SentryからのWebhookはJSON形式で飛んでくるのでパースする
app.use(bodyParser.json());

// ==========================================
// Webhook エンドポイントの定義
// ==========================================
app.post(‘/webhook’, (req, res) => {
// Sentryから送られてきたリクエストヘッダー（イベントの種類を特定するため）
const eventType = req.headers[‘sentry-hook-resource’];
const requestBody = req.body;

console.log(`\n🔥 [Sentry Alert] イベントを検知しました！`);
console.log(`- イベントタイプ: ${eventType}`);

// 今回は「Issue（エラーのグループ）」が新規作成・更新されたときをキャッチ
if (eventType === ‘issue’) {
const action = requestBody.action; // created, resolved など
const issue = requestBody.data.issue;
const project = requestBody.data.project;

console.log(`- アクション: ${action}`);
console.log(`- プロジェクト名: ${project.name}`);
console.log(`- エラータイトル: ${issue.title}`);
console.log(`- 詳細URL: ${issue.url}`);

// TODO: ここでSlack以外の自社チャットツール(LINE WORKS, Chatwork, Mattermostなど)のAPIを叩く！
}

// Sentryに対して「正常に受け取りました」と200 OKを即座に返す（これ重要）
res.status(200).send(‘Webhook Received Successfully’);
});

// サーバー起動
app.listen(PORT, () => {
console.log(`🚀 Sentry Internal Integration Server is running on port ${PORT}`);
});

—

4. ローカル環境で動作確認（ngrokの活用）

「よし、コードを書いたぞ！でもローカルホスト（`localhost:3000`）のままだと、Sentryのクラウドから通信できないのでは？」
鋭いね！その通り。クラウドサービスであるSentryからあなたのPCに通信を届けるために、`ngrok`（エングロック）という魔法のツールを使う。

1. [ngrokのサイト](https://ngrok.com/)からツールをダウンロードしてインストール（または適宜セットアップ）する。
2. ターミナルで以下のコマンドを叩く：

ngrok http 3000

3. 画面に表示される `https://xxxxxx.ngrok-free.app` のような公開URLをコピーする。
4. 先ほどSentryで作ったInternal Integrationの設定画面に戻り、Webhook URLに `https://xxxxxx.ngrok-free.app/webhook` を入力して保存する！

さあ、準備は整った。
Sentryのプロジェクト画面に戻り、テスト用のエラーを発生させてみよう。（適当なJavaScriptファイルで `throw new Error(“Hello Sentry Internal Integration!”);` を実行するだけでもいい）

うまく連携できていれば、あなたのローカルのターミナルに、こんな風にログが踊り出すはずだ！

🚀 Sentry Internal Integration Server is running on port 3000

🔥 [Sentry Alert] イベントを検知しました！

  • イベントタイプ: issue
  • アクション: created
  • プロジェクト名: my-awesome-frontend
  • エラータイトル: Error: Hello Sentry Internal Integration!
  • 詳細URL: https://sentry.io/organizations/…

どうだろう？
「おっ、つながった！」という実感が湧いたんじゃないかな。

—

5. さらに先へ：APIトークンを使ってSentryを自在に操る

Internal Integrationの真骨頂は、受信（Webhook）だけじゃない。
さきほど発行した `Token` を使えば、SentryのREST APIをノータイムで叩くことができる。

例えば、「社内チャットからの指示で、Sentry上の特定のエラーを強制的に解決済みにする（Resolve）」なんてことも、たった数行のコードで実現できるんだ。

const https = require(‘https’);

// SentryのInternal Integrationで発行されたトークン
const SENTRY_TOKEN = ‘sntry_your_generated_token_here’;
const ORGANIZATION_SLUG = ‘your-org-slug’;
const ISSUE_ID = ‘1234567890’; // 該当するIssueのID

const data = JSON.stringify({
status: ‘resolved’
});

const options = {
hostname: ‘sentry.io’,
path: `/api/0/issues/${ISSUE_ID}/`,
method: ‘PUT’,
headers: {
‘Authorization’: `Bearer ${SENTRY_TOKEN}`,
‘Content-Type’: ‘application/json’,
‘Content-Length’: data.length
}
};

const req = https.request(options, (res) => {
console.log(`ステータスコード: ${res.statusCode}`);
});

req.on(‘error’, (error) => {
console.error(error);
});

req.write(data);
req.end();

これを使えば、例えば「社内独自のSlack/Teamsボットから、リアクション絵文字をポチッと押すだけでSentryのエラーがクローズされる」といった、神がかった開発体験を構築できるようになる。

—

おわりに

今回は、Sentryの「Internal Integrations」を使って、社内ツールとの連携基盤を爆速で構築する方法を解説した。

OAuthの面倒な沼にハマることなく、わずか数分でセキュアかつ強力なAPI連携が手に入ったはずだ。
監視・運用という泥臭くなりがちな領域こそ、こうしたモダンでシンプルな拡張性を利用して、自分たちの手で心地よい環境にハックしていこう。

これをマスターしたあなたなら、毎日のエラー対応が少しだけ楽しく、そして圧倒的に楽になるはずだ。ぜひ、自社のワークフローに合わせた最高の自動化ボットを作ってみてくれよな！

スポンサーリンク
タイトルとURLをコピーしました