# バッチ設計書 49-pipeline-logging-functions.sh

## 概要

本ドキュメントは、パイプラインログ関数スクリプト（pipeline-logging-functions.sh）の設計仕様を記載したものです。このスクリプトは、Azure DevOpsパイプライン向けのログ出力関数を提供するライブラリスクリプトです。

### 本バッチの処理概要

このバッチは、他のビルドスクリプトから読み込まれて使用されるライブラリスクリプトです。Azure DevOpsの特殊なログコマンド（##vso[...]形式）を生成する関数を提供し、ビルドパイプラインとの統合を容易にします。

**業務上の目的・背景**：Azure DevOpsパイプラインでは、特殊なログコマンドを使用することで、変数の設定、エラーの記録、PATHの変更などをビルドログから直接行うことができます。このスクリプトにより、Bashスクリプトから一貫した方法でこれらのコマンドを生成できます。これにより、Arcadeフレームワーク全体でパイプライン統合の一貫性が保たれます。

**バッチの実行タイミング**：直接実行されるのではなく、tools.shから`source`コマンドで読み込まれます。

**主要な処理内容**：
1. `Write-PipelineTelemetryError`: テレメトリカテゴリ付きエラー出力
2. `Write-PipelineTaskError`: タスクエラー/警告の出力
3. `Write-PipelineSetVariable`: パイプライン変数の設定
4. `Write-PipelinePrependPath`: PATHへのディレクトリ追加
5. `Write-PipelineSetResult`: パイプライン結果の設定

**前後の処理との関連**：tools.shから読み込まれ、多くのArcadeスクリプトで使用されます。

**影響範囲**：Azure DevOpsのビルドログ、パイプライン変数、PATH環境変数に影響を与えます。

## バッチ種別

ライブラリスクリプト / ログ関数定義

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | tools.sh読み込み時に毎回 |
| 実行時刻 | 他スクリプトからの読み込み時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | sourceコマンドによる読み込み |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Bashシェル | /usr/bin/env bashで実行可能 |
| ci変数 | true/falseでCI環境を判定（tools.shで設定） |

### 実行可否判定

- 読み込み専用のライブラリスクリプトのため、常に読み込み可能

## 入力仕様

### 入力パラメータ

各関数は以下のパラメータを受け取ります：

**Write-PipelineTelemetryError**
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| -category / -c | string | Yes | テレメトリカテゴリ |
| -force / -f | flag | No | CI以外でも強制出力 |
| message | string | Yes | エラーメッセージ |

**Write-PipelineTaskError**
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| -type / -t | string | No | メッセージタイプ（error/warning） |
| -sourcepath / -s | string | No | ソースファイルパス |
| -linenumber / -ln | number | No | 行番号 |
| -columnnumber / -cn | number | No | 列番号 |
| -errcode / -e | string | No | エラーコード |
| -force / -f | flag | No | CI以外でも強制出力 |
| message | string | Yes | エラーメッセージ |

**Write-PipelineSetVariable**
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| -name / -n | string | Yes | 変数名 |
| -value / -v | string | Yes | 変数値 |
| -secret / -s | flag | No | シークレット変数として設定 |
| -as_output / -a | flag | No | 出力変数として設定 |
| -is_multi_job_variable / -i | boolean | No | マルチジョブ変数（デフォルトtrue） |

**Write-PipelinePrependPath**
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| -path / -p | string | Yes | PATHに追加するディレクトリ |

**Write-PipelineSetResult**
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| -result / -r | string | Yes | 結果（Succeeded/Failed等） |
| -message / -m | string | No | 結果メッセージ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 該当なし | - | 関数パラメータのみ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | Azure DevOpsログコマンド（##vso[...]形式） |
| 標準エラー | テキスト | CI以外での通常エラー出力 |
| PATH環境変数 | 文字列 | Write-PipelinePrependPathによる変更 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル出力 | なし |
| ログ出力先 | 標準出力 |
| フォーマット | ##vso[command key=value;...]message |

## 処理フロー

### 処理シーケンス

```
[Write-PipelineTelemetryError]
1. 引数解析
   └─ カテゴリ、force、メッセージを取得
2. CI環境判定
   └─ ci=falseかつforce=falseの場合は標準エラーに出力
3. テレメトリカテゴリの付与
   └─ (NETCORE_ENGINEERING_TELEMETRY=category)形式
4. Write-PipelineTaskError呼び出し

[Write-PipelineTaskError]
1. 引数解析
   └─ type、sourcepath、linenumber等を取得
2. CI環境判定
   └─ ci=falseかつforce=falseの場合は標準エラーに出力
3. ##vso[task.logissue]コマンド生成
   └─ オプションパラメータを連結
4. 標準出力に出力

[Write-PipelineSetVariable]
1. CI環境判定
   └─ ci=falseの場合は何もしない
2. 引数解析
   └─ name、value、secret、as_output等を取得
3. 値のエスケープ
   └─ ;→%3B、\r→%0D、\n→%0A、]→%5D
4. ##vso[task.setvariable]コマンド生成・出力

[Write-PipelinePrependPath]
1. 引数解析
   └─ pathを取得
2. PATHへの追加
   └─ export PATH="$prepend_path:$PATH"
3. CI環境判定
   └─ ci=trueの場合、##vso[task.prependpath]出力

[Write-PipelineSetResult]
1. 引数解析
   └─ result、messageを取得
2. CI環境判定
   └─ ci=trueの場合のみ出力
3. ##vso[task.complete]コマンド生成・出力
```

### フローチャート

```mermaid
flowchart TD
    A[関数呼び出し] --> B[引数解析]
    B --> C{CI環境?}
    C -->|No & !force| D[標準エラー出力]
    C -->|Yes または force| E[##vso[...]コマンド生成]
    E --> F[標準出力に出力]
    D --> G[終了]
    F --> G
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | このバッチはデータベース操作を行いません |

### テーブル別操作詳細

このバッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 該当なし | - | このスクリプト自体はエラーを発生させない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 該当なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

このスクリプトはログ出力のみを行うため、直接的な障害は発生しません。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 関数呼び出しごと |
| 目標処理時間 | ミリ秒単位 |
| メモリ使用量上限 | 最小（文字列操作のみ） |

## 排他制御

標準出力への同時書き込みによるインターリーブの可能性がありますが、通常の使用では問題になりません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | Write-PipelineTelemetryError時 | ##vso[task.logissue type=error;...]message |
| 警告ログ | Write-PipelineTaskError type=warning時 | ##vso[task.logissue type=warning;...]message |
| 変数設定 | Write-PipelineSetVariable時 | ##vso[task.setvariable variable=name;...]value |
| PATH変更 | Write-PipelinePrependPath時 | ##vso[task.prependpath]path |
| 結果設定 | Write-PipelineSetResult時 | ##vso[task.complete result=result;]message |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| エラーログ出力 | type=error | Azure DevOpsビルドサマリー |
| 警告ログ出力 | type=warning | Azure DevOpsビルドサマリー |

## 備考

- Azure DevOpsログコマンドのドキュメント：
  - https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/commands.md
- テレメトリカテゴリはNETCORE_ENGINEERING_TELEMETRYとして出力され、.NETのテレメトリシステムで収集されます
- CI環境判定はci変数（tools.shで設定）に基づきます
- 値のエスケープは以下の文字に対して行われます：
  - `;` → `%3B`
  - `\r` → `%0D`
  - `\n` → `%0A`
  - `]` → `%5D`
- Write-PipelinePrependPathはローカルのPATH環境変数も変更します（CI以外でも有効）
