よくある課題

TROCCOの設定を作成していく中で、以下のようなお悩みが発生しがちです。

• 設定のサマリーがなく、作成者以外が引き継ぐのに時間がかかる

• エラー時にどの部署へ連携すればよいかわからない

• 過去のエラー対応履歴が共有されていない

• YAMLに慣れていないユーザーが設定内容を把握しづらい

こうした課題を解消するために、メモ欄のテンプレートを活用する方法をご紹介します。

メモ欄テンプレート

メモ欄には「設定の概要・運用情報・トラブルシューティング・設定変更履歴」を記載することを推奨します。
以下に、運用者向けと閲覧者／依頼者向けの2種類のテンプレートを用意しました。Markdown 形式で用意したので、コピー&ペーストしてご利用ください。

転送設定の運用者向けテンプレート例

S3 -> BigQuery

# 概要
説明：〇〇システムが1時間おきにS3に配置したファイルのデータを都度BigQueryに転送する

## 転送元：S3
- バケット名：sample_bucket
- パスプレフィックス：sample/YYYYMMDD
- 入力ファイル形式：CSV
- 転送方法：差分転送（最終パス）

## 転送先：BigQuery
- データセット：sample_dataset
- テーブル：sample_table
- 転送モード：UPSERT（MERGE）
- マージキー：id,name

# 運用
- スケジュール：毎時30分に実行
- 転送処理時間目安：1分
- エラー発生時：slackチャンネル（sample_alerts）に通知
- 設定の管理者：〇〇チーム

# トラブルシューティング履歴
-- エラー発生時の対応や設定変更などの履歴

## 2025-10-01
```
[ERROR]: Error: org.jruby.exceptions.RaiseException: (Error) failed during waiting a Query job, get_job(xxx, embulk_query_job_xxx), errors:[{:reason=>"invalidQuery", :message=>"UPDATE/MERGE must match at most one source row for each target row", :location=>"query"}]
```
転送元のレコードに重複したレコードがある。マージキーの設定を修正（name->id,name）

## 日付
```
エラーログ
```
解消に向けてやったこと

MySQL -> kintone

# 概要
説明：自社サービスの顧客情報をkintoneに抽出する

## 転送元：MySQL
- 転送方法：差分転送
- テーブル名：sample_table
- 増分データを判別するカラム：id

## 転送先：kintone
- アプリID：111
- 転送モード：upsert
- アップデートキー：$id

# 運用
- スケジュール：毎朝9:00（Asia/Tokyo）
- 転送処理時間目安：30分
- エラー発生時：slackチャンネルに通知（cs_alerts）
- 設定の管理者：CSチーム

# トラブルシューティング履歴
-- エラー発生時の対応や設定変更などの履歴

## 2025-09-01
```
Error: java.lang.RuntimeException: com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link failure
```
STEP2入力オプションのソケットタイムアウトを1,800->3,600に修正

## 日付
```
エラーログ
```
解消に向けてやったこと

Google Ads -> S3

# 概要
説明：３日前のGoogle AdsのキャンペーンレポートをS3に転送する

## 転送元：Google Ads
- お客様ID：カスタム変数で２つのID（1111,2222）を展開するように指定
- リソースタイプ：Campaign
- データ取得期間：カスタム変数で３日前の日付（YYYY-MM-DD）を展開するように指定

## 転送先：S3
- バケット名：sample_bucket
- パスプレフィックス：sample/YYYYMMDD.csv
- 出力ファイル形式：CSV
- 転送モード：出力ファイル数抑制転送

# 運用
- スケジュール：毎朝9:00（Asia/Tokyo）
- 転送処理時間目安：1分
- エラー発生時：slackチャンネルに通知（marketing_alerts）
- 設定の管理者：マーケティング部

# トラブルシューティング履歴
-- エラー発生時の対応や設定変更などの履歴

## 2025-08-01
エラー発生時の通知先のslackチャンネルを cs_alerts -> marketing_alerts に変更

## 日付
```
エラーログ
```
解消に向けてやったこと

転送設定の閲覧者／依頼者向けテンプレート例

データの場所：MySQLの〇〇テーブルにあるデータを、BigQueryデータベースの〇〇テーブルに連携しています。
転送頻度：毎日9時に転送します。
連絡先：もしデータが転送されなくなったら、〇〇チーム or 〇〇さんに連絡してください。

データマート定義の運用者向けテンプレート例

# 概要
〇〇テーブルと〇〇テーブルをuser_idカラムでJOINさせて顧客情報のデータマートを作成する

# データソース
- クエリ実行モード：データ転送モード
- ウェアハウス：
- データベース：
- 元テーブル：〇〇テーブル、〇〇テーブル

# 転送先
- データベース：
- テーブル：〇〇テーブル
- 書き込み方法：append（追記）

# 運用
- 通知設定：なし
- スケジュール：毎日0時（Asia/Tokyo）

データマート定義の閲覧者／依頼者向けのテンプレート案

説明：〇〇テーブルと〇〇テーブルをuser_idカラムでJOINさせて顧客情報のデータマートを作成しています。
顧客別利用状況ダッシュボードで利用しています。
更新頻度：毎日9時に更新されます。
連絡先：もしデータが更新されなくなったら、〇〇チーム or 〇〇さんに連絡してください。

ワークフローテンプレート例

# 説明
1. 各種広告コンテンツの３日前のレポートをBigQueryに転送
2. 各レポートデータが１件以上あった場合はローデータを加工する処理を実施
3. BigQueryへローデータ転送後、各種レポートの加工処理を実施するデータマート作成

Google Ads 対象レポート
- ad
- campaign
- ad_group

Yahoo!検索広告 対象レポート
- AD
- ACCOUNT
- CAMPAIGN

X Ads 対象レポート
- account
- campaign

TikTok Ads 対象レポート
- ad
- campaign

# 運用
- 通知：ワークフロー終了時slackチャンネルに通知（marketing_notes）
- スケジュール：毎日9:00（Asia/Tokyo）

まとめ

• メモ欄に「設定の概要・運用に関する情報・トラブルシューティング」を記録すると、引き継ぎや障害対応がスムーズになる

• 閲覧者向けには簡易的なテンプレートを用意することで、TROCCOに精通していないユーザーに対しても情報共有がシンプルにできる

こうして運用ルールを整えておくと、設定管理の効率化とナレッジ共有が大幅に進みます。