Skip to content

Latest commit

 

History

History
143 lines (96 loc) · 4.98 KB

syntax.ja.md

File metadata and controls

143 lines (96 loc) · 4.98 KB
Raw

daifuku ログ定義用 Markdown 形式

要素

ログはカテゴリ、イベント、カラムの3要素からなります。

  • カテゴリ：イベントの集合。近しい機能を同一のカテゴリとして扱う（RecipeSearchなど）
  • イベント：ログを送るきっかけとなる動作単位
  • カラム：イベントの持つ値。型と名前を持つ

それぞれの名前は /\w+/ であることが期待されています。

ログ定義の記述

# recipe_search

レシピ検索に関するログです。

## search

ユーザーがレシピをキーワード検索したときに送信されます。

- keyword: !string 256
   - 検索キーワード
- order: SearchOrder
   - 新着順, 人気順

## show_recipe

ユーザーが検索結果画面でレシピを選択したときに送信されます。

- recipe_id: !integer
    - 選択されたレシピのID
- position: !integer
  - タップしたクエリが上から何番目か (0始まり)

カテゴリ

ドキュメントのトップレベルに記述した文章は全てカテゴリの説明として扱われます。

文中のインライン要素は十分にテストされていません。 文章の記述にはボールドやコードブロックなどのインライン要素を使わない方が無難です。

仕様上はカテゴリ共通カラムの定義が可能ですが、現段階では未対応です。

ファイル名がカテゴリ名として扱われますが、分かりやすさのために、# 見出しをファイル名と同じにしましょう。snake_caseが推奨されます。

イベント

## 見出し以下の文章はイベントの説明、カラム定義はイベント内のカラムとして扱われます。

見出しがイベント名として扱われます。snake_caseが推奨されます。

カラム

イベント以下にあるリスト要素はカラムとして扱われます。カラムは以下のようなシンタックスで定義できます。

- <カラム名>: !<カラム型>(?)
    - カラムの説明1
    - カラムの説明2

型

  • !から始まる型はプリミティブ型です。
  • 末尾に?をつけることでオプショナル型として定義することができます。
  • 未知の型を利用したとき、生成に失敗します。

クックパッドでは データウェアハウス に Amazon Redshift を利用しており、Redshift でサポートされているデータ型を前提として以下の利用可能な型を定義しています。

  • !smallint : 16ビット符号付き整数
  • !integer : 32ビット符号付き整数
  • !bigint : 64ビット符号付き整数
  • !real : 32ビット浮動小数点数
  • !double : 64ビット浮動小数点数
  • !boolean : 真偽値
  • !string <バイト数> : 文字列型
  • !date : 日付型
  • !timestamp : 日付時刻型（タイムゾーンなし）
  • !timestamptz : 日付時刻型（タイムゾーンあり）

文字列型は定義時に文字列長の指定が可能です。

- message: !string 256

カスタム型

カスタム型を定義、利用することもできます。 アプリケーション側で enum などを定義して特定の定義域を表現するのに利用できます。

ログ定義側でカスタム型を利用するには、!から始まらない型名を直接指定してください。

# user

## set_profile

- user_status: UserStatus
    - ユーザー状態

obsolete指定

利用しなくなったイベントやカラムには [obsolete] 指定が使えます。これを含んだイベントやカラムはコード生成から除外されますが、古いログの調査のためにドキュメントには残ります。

descriptionに使用できなくなったアプリのバージョン名を明記しておくと便利です。

- [obsolete] user_status: UserStatus
    - ユーザー状態
    - v2020.34.0 から廃止されました

CommonPayload

すべてのイベントが共通して持つカラムをCommonPayloadと呼んでいます。 これはUser AgentやユーザーID、OSバージョンなどを想定しています。

commonというカテゴリ名のログ定義は特別にCommonPayloadとして扱われます。 すなわち、LogDefinitions/common.mdにカラムを記述することで、CommonPayloadとして処理されます。

記述方法は普通のカテゴリと同様ですが、トップレベルのカラムだけがパースされ、イベント定義は無視されます。

# common

- user_id: !bigint?
    - ユーザーID
- user_agent: !string 1000
    - ユーザーエージェント
- os_version: !string 32
    - iOSバージョン
- application_version: !string 32
    - アプリケーションバージョン
- time_zone: !string 64
    - タイムゾーン(Asia/Tokyoなど)