Databricksの利用課金データのデリバリーとアクセス

[Deliver and access billable usage logs \| Databricks on AWS](https://docs.databricks.com/administration-guide/account-settings/billable-usage-delivery.html) [2022/9/27時点]の翻訳です。

:::note warn
本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。
:::

:::note info
**プレビュー**
本機能は[パブリックプレビュー](https://docs.databricks.com/release-notes/release-types.html)です。
:::

Databricksのアカウントオーナー、あるいは[アカウント管理者](https://docs.databricks.com/administration-guide/account-settings-e2/admin-users.html)として、[利用量分析](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2#databricks%E3%81%A7%E5%88%A9%E7%94%A8%E3%83%AD%E3%82%B0%E3%82%92%E5%88%86%E6%9E%90%E3%81%99%E3%82%8B)でデータを利用できる様にAWS S3バケットにCSVファイル形式で利用課金ログを日次でデリバリーする様に設定することができます。お使いのアカウントのワークスペースごとのCSVファイルをデリバリーします。このCSVファイルには、ワークスペースのクラスター利用量を、クラスターID、課金SKU、クラスター作成者、クラスタータグなどで並び替えできるDatabricksユニット(DBU)の形式の履歴データが含まれます。CSVファイルのそれぞれのカラムの説明については、[CSVファイルのスキーマ](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2#csv%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E)を参照ください。

ログデリバリーを設定せずに利用課金データをダウンロードするためにAPIを使うには、[Download billable usage logs using the Account API](https://docs.databricks.com/administration-guide/account-settings/billable-usage-download-api.html)をご覧ください。

お使いのアカウントがE2バージョンのプラットフォームであれば、アカウントオーナーとアカウント管理者は[E2向けアカウントコンソールの利用量ページ](https://docs.databricks.com/administration-guide/account-settings-e2/index.html)でグラフやテーブル形式で利用量を確認することができます。このページでは、ワークロードタイプごとにグルーピングされたDBUの使用量をグラフで表示することができ、CSV形式で利用量データを直接ダウンロードすることができます。

:::note info
**注意**
すべての新規Databricksアカウントと大部分の既存アカウントはE2です。もし、自分のアカウントタイプが不明な場合にはDatabricks担当者にお問い合わせください。
:::

別のバージョンのアカウントの場合には、アカウントオーナーは[レガシーなアカウントコンソールの利用量概要タブ](https://docs.databricks.com/archive/admin-guide/usage.html)で利用量を確認することができます。

オプションとして、ログデリバリーのために作成したIAMロールとは異なるAWSアカウントにログをデリバリーすることができます。これによって、複数のAWSアカウントが同じS3バケットにデリバリーする様にワークスペースを設定するなどの柔軟性を手に入れることができます。このオプションでは、クロスアカウントのIAMロールを参照するS3バケットポリシーを設定する必要があります。本書では、手順とポリシーテンプレートを提供します。

S3バケットをどの様にセットアップするのかによって、アカウントオーナーとアカウント管理者によるログへのアクセス方法が異なります。Databricksは、AWSビルトインの[BucketOwnerFullControl Canned ACL](https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html)を用いてS3バケットにログをデリバリーするので、アカウントオーナーと割り当てられたユーザーは直接ログをダウンロードすることができます。新規作成されたオブジェクトのバケットオーナーシップをサポートするためには、お使いのバケットの**S3 Object Ownership**を**Bucket owner preferred**に設定する必要があります。

:::note warn
**重要！**
設定**S3 Object Ownership**を**Object writer**にすると、ログの様な新規オブジェクトのオーナーはアップロードしたアカウントであり続けます。これはデフォルトでは、お使いのバケットへのアクセスのために作成、指定されたIAMロールとなります。この場合、AWSコンソールやバケットオーナーとして認証した自動化ツールからアクセスすることができないため、ログへのアクセスが困難となります。
:::

望ましくないアクセスからバケットのデータを防御するガイドに関しては、[Security Best Practices for S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/security-best-practices.html)をレビューすることをお勧めします。

# 設定の選択肢

利用課金ログデリバリーを設定する際、アカウントが[E2バージョンプラットフォーム](https://qiita.com/taka_yayoi/items/7d209bc8d32bc5f2dba4#e2%E3%82%A2%E3%83%BC%E3%82%AD%E3%83%86%E3%82%AF%E3%83%81%E3%83%A3)である場合、以下の選択肢があります。

- アカウント内のすべてのワークスペースで同じ設定(ログデリバリーのS3バケットとIAMロール)を共有する。これはデフォルトです。
- アカウント内のワークスペースごとに別の設定を使用する。
- 別々のワークスペースのグループごとに設定を共有する。

[Account API](https://docs.databricks.com/administration-guide/account-api/new-workspace.html)や[E2アカウントのアカウントコンソール](https://docs.databricks.com/administration-guide/account-settings-e2/index.html#account-console)を用いてワークスペースが作成されていない場合、アカウントごとに1つのワークスペースを持つことしかできません。このため、アカウントごとにユニークなストレージ設定オブジェクト、認証設定オブジェクトを作成しなくてはなりませんが、これらの設定オブジェクトでS3バケットやIAMロールを再利用することができます。

:::note info
**注意**
ログデリバリーを設定するためにAccount APIを使用したとしても、Account APIを使用せずに作成されたワークスペースを含め、いかなるワークスペースでログデリバリーを設定することができます。
:::

# ハイレベルのフロー

利用課金ログのデリバリーのハイレベルのフローは以下の通りとなります。

1. [ストレージの設定](#ステップ1-ストレージの設定): AWSで新規のAWS S3バケットを作成します。Databricks APIを用いて、そのバケット名を使用するストレージ設定オブジェクトを作成するためにAccount APIを呼び出します。

    :::note info
    **注意**
    ログデリバリーのために作成したIAMロールとは異なるAWSアカウントにログをデリバリーするには、S3バケットポリシーを追加する必要があります。このステップではなく、後のステップで追加を行います。
   :::

1. [認証情報の設定](#ステップ2-認証情報の設定): AWSで適切なAWS IAMロールを作成します。Databricks APIを用いて、IAMロールのARNを使用する認証設定オブジェクトを作成するためにAccount APIを呼び出します。ロールポリシーでは、お使いのS3バケット内でログデリバリーのためのパスプレフィックスを指定することができます。ログデリバリーの設定で、S3バケットを共有しながらも、ワークスペースごとに異なるパスプレフィックスを使用する様に複数のパスプレフィックスを含める様にIAMロールを定義することもできます。
1. [(オプション)クロスアカウントのサポート](#ステップ3-オプションクロスアカウントのサポート): ログデリバリーのために作成したIAMロールとは異なるAWSアカウントにログをデリバリーする際には、S3バケットポリシーを追加します。このポリシーは、以前のステップで作成したクロスアカウントIAMロールに対するIDを参照します。
1. [log delivery APIの呼び出し](#ステップ4-log-delivery-apiの呼び出し): 以前のステップで作成した認証情報設定オブジェクト、ストレージ設定オブジェクトを使用するログデリバリー設定を作成するためにAccount APIを呼び出します。このステップでは、ログデリバリー設定をアカウント全体(現在、将来のワークスペース)、あるいは特定のワークスペースに関連づけることができます。
1. [分析のためにCSVファイルにアクセス](#ステップ5-分析のためにログファイルにアクセス): デリバリーのロケーションは`<bucket-name>/<prefix>/billable-usage/csv/`であり、`<prefix>`はログデリバリーの設定でセットアップしたオプションのデリバリーパスのプレフィックスとなります。ファイル名は、`workspaceId=<workspace-id>-usageMonth=<month>.csv`となります。ファイルは、ワークスペースごと月ごとのCSVファイルを上書きすることでデリバリーされます。分析のためにこのデータをDatabricksにインポートすることができます。また、これらのCSVファイルをベースとして利用量分析ダッシュボードを実行するためのノートブックがあります。詳細は[Databricksで利用ログを分析する](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2#databricks%E3%81%A7%E5%88%A9%E7%94%A8%E3%83%AD%E3%82%B0%E3%82%92%E5%88%86%E6%9E%90%E3%81%99%E3%82%8B)をご覧ください。

:::note warn
**重要！**
アカウントで作成できるログデリバリー設定の数には制限があります。アカウントレベル(ワークスペースのフィルタなし)では最大2つの有効な設定を作成することができ、有効な2つの設定はすべて固有のワークスペースに割り当てられます(2つの設定のワークスペースフィルタで同じ`workspaceId`が含まれることは許容されます)。ログデリバリー設定を削除することはできませんが、無効化することはできます。無効化した設定を再度有効化することはできますが、上述した様に制限を超えるリクエストは失敗します。
:::

# 要件

- APIの認証を受けるためのアカウントオーナー([E2アカウント](https://docs.databricks.com/administration-guide/account-settings-e2/admin-users.html)の場合はアカウント管理者も)のメールアドレスとパスワード

    メールアドレスとパスワードは大文字小文字を区別します。

- アカウントID

    E2バージョンのプラットフォームのアカウントでは、[アカウントコンソール](https://accounts.cloud.databricks.com/)のユーザープロファイルのドロップダウンからアカウントIDを取得することができます。E2バージョンでない場合、アカウントコンソールの[Usage Overviewタブ](https://accounts.cloud.databricks.com/#usage)からアカウントIDを取得できます。アカウントIDが見つからない場合にはDatabricks担当者にコンタクトしてください。

# APIの認証方法

本書で説明されているAPIはすべてのAWSリージョナルデプロイメントに対して`accounts.cloud.databricks.com`のベースエンドポイントで公開されています。

APIリクエストのためには以下のベースURLを使用します。
`https://accounts.cloud.databricks.com/api/2.0/`

REST APIには、HTTPヘッダー`Authorization`の設定を含むHTTP Basic認証が必要となります。本書では、*username*はあなたのアカウントオーナー(あるいは、[E2アカウント](https://docs.databricks.com/administration-guide/account-settings-e2/admin-users.html)の場合はアカウント管理者)のメールアドレスを参照します。このメールアドレスは大文字小文字を区別します。認証情報をcurlの様なツールに提供するにはいくつかの方法があります。

- `<username>:<password>`の構文でそれぞれのリクエストのヘッダーでアカウントのユーザー名とパスワードを指定します。

    ```sh:Bash
    curl -X GET -u `<username>:<password>` -H "Content-Type: application/json" \
   'https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/<endpoint>'
    ```

- `<username>:<password>`文字列にbase64エンコーディングを適用し、HTTPヘッダーに直接指定します。

    ```sh:Bash
    curl -X GET -H "Content-Type: application/json" \
  -H 'Authorization: Basic <base64-username-pw>'  'https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/<endpoint>'
    ```

- `machine`、`login`、`password`プロパティを持つ[\.netrc](https://everything.curl.dev/usingcurl/netrc)ファイルを作成します。

    ```ini:ini
    machine accounts.cloud.databricks.com
    login <username>
    password <password>
    ```

    `.netrc`ファイルを呼び出すには、`curl`コマンドで`-n`を使います。

    ```sh:Bash
    curl -n -X GET 'https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/workspaces'
    ```

    本書の例では、この認証スタイルを使用します。

完全なAPIリファレンスに関しては、[Account API 2\.0](https://docs.databricks.com/dev-tools/api/latest/account.html)をご覧ください。

# ステップ1: ストレージの設定

Databricksは利用課金データをお使いのアカウントのS3バケットにデリバリーします。複数のワークスペースが単一のS3バケットを用いる様に、あるいは、ワークスペースごと(あるいはワークスペースのグループごと)に異なるバケットを使用する様に定義することができます。

この手順では、アカウントの1つ以上のワークスペースで共通の設定を用いる単一の設定オブジェクトをどの様にセットアップするのか説明します。ワークスペースごとに別のストレージロケーションを使用するには、ワークスペースごとあるいはワークスペースのグループごとに手順を繰り返します。

1. [Configure AWS storage](https://docs.databricks.com/administration-guide/account-api/aws-storage.html)の手順に従ってS3バケットを作成します。
1. 新規S3バケットを表現するDatabricksストレージ設定レコードを作成します。[新規ストレージ設定作成API](https://docs.databricks.com/dev-tools/api/latest/account.html#operation/create-storage-config)(`POST /accounts/<account-id>/storage-configurations`)を呼び出すことでS3バケットを指定します。

    以下を指定します。

    - `storage_configuration_name` - ユニークな新規ストレージ設定名
    - `root_bucket_info` - お使いのS3バケット名を含む`bucket_name`フィールドを持つJSONオブジェクト

    レスポンスの本体に含まれる`storage_configuration_id`の値をコピーします。以降のステップでログデリバリー設定を作成する際にこれを使用します。

    サンプル:

    ```sh:Bash
    curl -X POST -n \
        'https://accounts.cloud.databricks.com/api/2.0/accounts/<databricks-account-id>/storage-configurations' \
      -d '{
        "storage_configuration_name": "databricks-workspace-storageconf-v1",
        "root_bucket_info": {
          "bucket_name": "my-company-example-bucket"
        }
      }'
    ```

    レスポンス:

    ```json:JSON
    {
      "storage_configuration_id": "<databricks-storage-config-id>",
      "account_id": "<databricks-account-id>",
      "root_bucket_info": {
        "bucket_name": "my-company-example-bucket"
      },
      "storage_configuration_name": "databricks-workspace-storageconf-v1",
      "creation_time": 1579754875555
    }
    ```

# ステップ2: 認証情報の設定

この手順では、アカウントの1つ以上のワークスペースで共通する単一の設定のセットアップ方法を説明します。ワークスペースごとに異なる認証情報を使用するには、ワークスペースごとあるいはワークスペースのグループごとに手順を繰り返します。

:::note info
**注意**
異なるS3バケット名を使用するには、別のIAMロールを作成する必要があります。
:::

1. 管理者権限を持つユーザーとしてAWSコンソールにログインし、**IAM**サービスに移動します。
1. サイドバーから**Roles**タブをクリックします。
1. **Create role**をクリックします。
    1. **Select type of trusted entity**で**AWS service**をクリックします。
    1. **Common Use Cases**で**EC2**をクリックします。
    1. **Next: Permissions**ボタンをクリックします。
    1. **Next: Tags**ボタンをクリックします。
    1. **Next: Review**ボタンをクリックします。
    1. **Role name**フィールドにロール名を入力します。
![](https://docs.databricks.com/_images/role-name.png)
    1. **Create role**をクリックします。ロール一覧が表示されます。
1. ロール一覧で、作成したロールをクリックします。
1. インラインポリシーを追加します。
    1. Permissionsタブで**Add inline policy**をクリックします。
![](https://docs.databricks.com/_images/inline-policy.png)
    1. ポリシーエディタで**JSON**タブをクリックします。
![](https://docs.databricks.com/_images/policy-editor.png)
    1. アクセスポリシーをコピーして修正します。ポリシーの以下の値をご自身の設定値で置き換えます。

    - `<s3-bucket-name>`: お使いのAWS S3バケットのバケット名
    - `<s3-bucket-path-prefix>`: (オプション)S3バケットのデリバリーロケーションへのパス。指定されない場合、ログはバケットのルートにデリバリーされます。このパスは[log delivery APIを呼び出す](#ステップ4-log-delivery-apiの呼び出し)際の引数`delivery_path_prefix`と一致する必要があります。

    ```json:JSON
    {
      "Version":"2012-10-17",
      "Statement":[
        {
          "Effect":"Allow",
          "Action":[
            "s3:GetBucketLocation"
          ],
          "Resource":[
            "arn:aws:s3:::<s3-bucket-name>"
          ]
        },
        {
          "Effect":"Allow",
          "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:DeleteObject",
            "s3:PutObjectAcl",
            "s3:AbortMultipartUpload"
          ],
          "Resource":[
            "arn:aws:s3:::<s3-bucket-name>/<s3-bucket-path-prefix>/",
            "arn:aws:s3:::<s3-bucket-name>/<s3-bucket-path-prefix>/*"
          ]
        },
        {
          "Effect":"Allow",
          "Action":[
            "s3:ListBucket",
            "s3:ListMultipartUploadParts",
            "s3:ListBucketMultipartUploads"
          ],
          "Resource":"arn:aws:s3:::<s3-bucket-name>",
          "Condition":{
            "StringLike":{
              "s3:prefix":[
                "<s3-bucket-path-prefix>",
                "<s3-bucket-path-prefix>/*"
              ]
            }
          }
        }
      ]
    }
    ```

    パスプレフィックスの使用法をカスタマイズすることができます。

    - バケットパスのプレフィックスを使いたくない場合には、`<s3-bucket-path-prefix>/`(最後のスラッシュを含みます)が表示される箇所を削除してください。
    - 複数のワークスペースでS3バケットは共有しますが、異なるパスプレフィックスを使用したい場合、複数のパスプレフィックスを含める様にIAMロールを定義することができます。`<s3-bucket-path-prefix>`を参照する部分が2ヶ所ポリシーに存在します。それぞれのケースで、パスプレフィックスを参照する連続する2行を複製します。以下の様に、新たなパスプレフィックスごとに行のペアを繰り返します。
    ```json:JSON
    {
      "Resource":[
        "arn:aws:s3:::<mybucketname>/field-team/",
        "arn:aws:s3:::<mybucketname>/field-team/*",
        "arn:aws:s3:::<mybucketname>/finance-team/",
        "arn:aws:s3:::<mybucketname>/finance-team/*"
      ]
    }
    ```
    1. **Reveiw policy**をクリックします。
    1. **Name**フィールドでポリシー名を入力します。
    1. **Create policy**をクリックします。
    1. AWSアカウントレベルで特定のアクションを拒否するサービスコントロールポリシーを使用しているのであれば、Databricksがクロスアカウントロールを仮定できるように`sts:AssumeRole`が許可されていることを確認してください。 

1. ロールのサマリーページで**Trust Relationships**タブをクリックします。
1. エディタに以下のアクセスポリシーを貼り付け、以下の値をご自身の設定値で置き換えます。

    - `<databricks-account-id>`: お使いのDatabricksアカウントID

    ```json:JSON
    {
      "Version":"2012-10-17",
      "Statement":[
        {
          "Effect":"Allow",
          "Principal":{
            "AWS":"arn:aws:iam::414351767826:role/SaasUsageDeliveryRole-prod-IAMRole-3PLHICCRR1TK"
          },
          "Action":"sts:AssumeRole",
          "Condition":{
            "StringEquals":{
              "sts:ExternalId":[
                "<databricks-account-id>"
              ]
            }
          }
        }
      ]
    }
    ```

1. ロールサマリーページで**Role ARN**をコピーしておき、後のステップのために保存しておきます。
![](https://docs.databricks.com/_images/role-arn.png)

1. IAMロールに対応するDatabricks認証設定IDを作成します。[認証設定作成API](https://docs.databricks.com/dev-tools/api/latest/account.html#operation/create-credential-config)(`POST /accounts/<account-id>/credentials`)を呼び出します。このリクエストはクロスアカウントの信頼関係を確立し、新たなワークスペースを作成する際に使用するリファレンスIDを返却します。

    `<account-id>`をお使いのDatabricksアカウントIDで置き換えます。リクエスト本体では、

    - `credentials_name`にはお使いのアカウントで一位の名前をつけます。
    - `aws_credentials`には、`sts_role`プロパティを含むオブジェクトを設定します。このオブジェクトでは、作成したロールの`role_arn`を指定する必要があります。

    レスポンスのボディには、新規ワークスペースを作成する際に必要となるDatabricks認証設定のIDである`credentials_id`フィールドが含まれます。後ほどのステップでログデリバリー設定を作成する際に使用するのでこのフィールドをコピーしておきます。

    サンプル:

    ```sh:Bash
     curl -X POST -n \
       'https://accounts.cloud.databricks.com/api/2.0/accounts/<databricks-account-id>/credentials' \
       -d '{
       "credentials_name": "databricks-credentials-v1",
       "aws_credentials": {
         "sts_role": {
           "role_arn": "arn:aws:iam::<aws-account-id>:role/my-company-example-role"
         }
       }
     }'
    ```

    レスポンス:

    ```json:JSON
     {
       "credentials_id": "<databricks-credentials-id>",
       "account_id": "<databricks-account-id>",
       "aws_credentials": {
         "sts_role": {
           "role_arn": "arn:aws:iam::<aws-account-id>:role/my-company-example-role",
           "external_id": "<databricks-account-id>"
         }
       },
       "credentials_name": "databricks-credentials-v1",
       "creation_time": 1579753556257
     }
    ```

   後で使うので、レスポンスの`credentials_id`をコピーしておきます。

# ステップ3: (オプション)クロスアカウントのサポート

ログデリバリーで使うIAMロールと同じAWSアカウントにS3バケットがある場合には、このステップはスキップしてください。

ログデリバリーのために作成したIAMロールがあるアカウントと異なるAWSアカウントにログをデリバリーするためには、以下で説明するS3バケットポリシーを追加します。このポリシーは、以前のステップで作成したクロスアカウントIAMロールのIDを参照します。

1. AWSコンソールからS3サービスに移動します。
1. バケット名をクリックします。
1. **Permissions**タブをクリックします。
1. **Bucket Policy**ボタンをクリックします。
![](https://docs.databricks.com/_images/bucket-policy.png)

1. バケットポリシーをコピーし編集します。

    `<s3-bucket-name>`をお使いのS3バケット名で置き換えます。`<customer-iam-role-id>`を新規に作成したIAMロールのロールIDで置き換えます。`<s3-bucket-path-prefix>`を希望のバケットパスプレフィックスで置き換えます。パスプレフィックスンポカスタマイズに関する情報についてはポリシーサンプルの後にある注意を参照ください。

    ```json:JSON
    {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Principal": {
                  "AWS": ["arn:aws:iam::<customer-iam-role-id>"]
              },
              "Action": "s3:GetBucketLocation",
              "Resource": "arn:aws:s3:::<s3-bucket-name>"
          },
          {
              "Effect": "Allow",
              "Principal": {
                  "AWS": "arn:aws:iam::<customer-iam-role-id>"
              },
              "Action": [
                  "s3:PutObject",
                  "s3:GetObject",
                  "s3:DeleteObject",
                  "s3:PutObjectAcl",
                  "s3:AbortMultipartUpload",
                  "s3:ListMultipartUploadParts"
              ],
              "Resource": [
                  "arn:aws:s3:::<s3-bucket-name>/<s3-bucket-path-prefix>/",
                  "arn:aws:s3:::<s3-bucket-name>/<s3-bucket-path-prefix>/*"
              ]
          },
          {
              "Effect": "Allow",
              "Principal": {
                  "AWS": "arn:aws:iam::<customer-iam-role-id>"
              },
              "Action": "s3:ListBucket",
              "Resource": "arn:aws:s3:::<s3-bucket-name>",
              "Condition": {
                  "StringLike": {
                      "s3:prefix": [
                          "<s3-bucket-path-prefix>",
                          "<s3-bucket-path-prefix>/*"
                      ]
                  }
              }
          }
      ]
    }
    ```

    パスプレフィックスの使用法をカスタマイズすることができます。

    - バケットパスのプレフィックスを使いたくない場合には、`<s3-bucket-path-prefix>/`(最後のスラッシュを含みます)が表示される箇所を削除してください。
    - 複数のワークスペースでS3バケットは共有しますが、異なるパスプレフィックスを使用したい場合、複数のパスプレフィックスを含める様にIAMロールを定義することができます。`<s3-bucket-path-prefix>`を参照する部分が2ヶ所ポリシーに存在します。それぞれのケースで、パスプレフィックスを参照する連続する2行を複製します。以下の様に、新たなパスプレフィックスごとに行のペアを繰り返します。
    ```json:JSON
    {
      "Resource":[
        "arn:aws:s3:::<mybucketname>/field-team/",
        "arn:aws:s3:::<mybucketname>/field-team/*",
        "arn:aws:s3:::<mybucketname>/finance-team/",
        "arn:aws:s3:::<mybucketname>/finance-team/*"
      ]
    }
    ```

# ステップ4: log delivery APIの呼び出し

ログデリバリーを設定するには、ログデリバリー設定API(`POST /accounts/<account-id>/log-delivery`)をコールします。

以前のステップでコピーした以下の値が必要となります。

- `credentials_id`: クロスアカウントロールの認証情報を表現するDatabricks認証設定ID。
- `storage_configuration_id`: お使いのルートS3バケットを表現するDatabricksストレージ設定ID。

また、以下のフィールドを設定します。

- `log_type`: 常に`BILLABLE_USAGE`に設定します。
- `output_format`: 常に`CSV`に設定します。CSVファイルフォーマットの詳細については、[Databricksにおける利用課金ログデータの分析](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2)をご覧下さい。
- `delivery_path_prefix`: (オプション)パスプレフィックスを設定します。ロールポリシーで使用したパスプレフィックスとマッチする必要があります。
- `workspace_ids_filter`: (オプション)デフォルトでは、このログ設定はお使いのアカウントIDに紐づけられるすべてのワークスペースに適用されます。いくつかのタイプのデプロイメントでは、アカウントIDごとに一つのワークスペースしか存在しないので、このフィールドは不要です。あなたのアカウントでワークスペースがAccount APIを用いて作成された場合、アカウントIDに複数のワークスペースが関連づけられている場合があります。オプションとして、設定を適用するワークスペースの配列をこのフィールドに設定することができます。別のワークスペースには別のログデリバリー設定を使用することを考えているのであれば、ブランクのままとするのではなく明示的に設定してください。これをブランクにすると、お使いのアカウントIDは今後作成される他のワークスペースにも関連づけられるので、この設定も新規ワークスペースに適用されます。ワークスペースには1つ以上のログデリバリー設定を適用することができ、この場合には複数のロケーションにログが書き込まれます。

    :::note warn
    **重要！**
    アカウントで作成できるログデリバリー設定の数には制限があります。アカウントレベル(ワークスペースのフィルタなし)では最大2つの有効な設定を作成することができ、有効な2つの設定はすべて固有のワークスペースに割り当てられます(2つの設定のワークスペースフィルタで同じ`workspaceId`が含まれることは許容されます)。ログデリバリー設定を削除することはできませんが、無効化することはできます。無効化した設定を再度有効化することはできますが、上述した様に制限を超えるリクエストは失敗します。
  :::

    - `delivery_start_time`: (オプション)ログデリバリーを開始する年月です。デフォルトは現在の月ですう。フォーマットはテキストで`YYYY-MM`形式となります。2019-03以降の任意の年月を指定することができます。

サンプル:

```bash:Bash
curl -X POST -n \
  'https://accounts.cloud.databricks.com/api/2.0/accounts/<databricks-account-id>/log-delivery' \
  -d '{
  "log_delivery_configuration": {
    "log_type": "BILLABLE_USAGE",
    "config_name": "billable usage config",
    "output_format": "CSV",
    "credentials_id": "<databricks-credentials-id>",
    "storage_configuration_id": "<databricks-storage-config-id>",
    "delivery_path_prefix": "usage-data",
    "delivery_start_time": "2020-06",
    "workspace_ids_filter": [
        6383650456894062,
        4102272838062927
    ]
    }
}'
```

レスポンス:

```json:JSON
{
    "log_delivery_configuration": {
        "config_id": "<config-id>",
        "config_name": "billable usage config",
        "log_type": "BILLABLE_USAGE",
        "output_format": "CSV",
        "account_id": "<account-id>",
        "credentials_id": "<databricks-credentials-id>",
        "storage_configuration_id": "<databricks-storage-config-id>",
        "workspace_ids_filter": [
            6383650456894062,
            4102272838062927
        ],
        "delivery_path_prefix": "usage-data",
        "delivery_start_time": "2020-06",
        "status": "ENABLED",
        "creation_time": 1591638409000,
        "update_time": 1593108904000,
        "log_delivery_status": {
          "status": "CREATED",
          "message": "Log Delivery Configuration is successfully created. Status will be updated after the first delivery attempt."
        }
    }
}
```

## log delivery APIのその他の機能

[log delivery API](https://docs.databricks.com/dev-tools/api/latest/account.html#tag/Log-delivery-configurations)には、その他の機能があります。詳細についてはAPIリファレンスのドキュメントをご覧ください。

その他の機能には以下の様なものがあります。

- [すべてのログデリバリー設定の取得](https://docs.databricks.com/dev-tools/api/latest/account.html#operation/get-log-delivery-configs)
- [IDを指定してログデリバリー設定を取得](https://docs.databricks.com/dev-tools/api/latest/account.html#operation/get-log-delivery-config)
- [IDを指定してログデリバリー設定を有効化、無効化](https://docs.databricks.com/dev-tools/api/latest/account.html#operation/patch-log-delivery-config-status)

ログデリバリー設定のステータスは、APIレスポンスの`log_delivery_status`オブジェクトで確認することができます。`log_delivery_status`を用いることで、ステータス(成功あるいは失敗)とデリバリーの試行や成功の最後の日付をチェックすることができます。

:::note warn
**重要！**
アカウントで作成できるログデリバリー設定の数には制限があります。アカウントレベル(ワークスペースのフィルタなし)では最大2つの有効な設定を作成することができ、有効な2つの設定はすべて固有のワークスペースに割り当てられます(2つの設定のワークスペースフィルタで同じ`workspaceId`が含まれることは許容されます)。ログデリバリー設定を削除することはできませんが、無効化することはできます。無効化した設定を再度有効化することはできますが、上述した様に制限を超えるリクエストは失敗します。
:::

# ステップ5: 分析のためにログファイルにアクセス

ログは`<bucket-name>/<prefix>/billable-usage/csv/`にデリバリーされ、`<prefix>`はログデリバリーの設定でセットアップしたオプションのデリバリーパスのプレフィックスとなります。ファイル名は、`workspaceId=<workspace-id>-usageMonth=<month>.csv`となります。ファイルは、ワークスペースごと月ごとのCSVファイルを上書きすることでデリバリーされます。

CSVのスキーマについては、[CSVファイルスキーマ](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2#csv%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E3%82%B9%E3%82%AD%E3%83%BC%E3%83%9E)をご覧ください。

Databricksを用いたこれらのファイルの分析方法の詳細は[Databricksで利用ログを分析する](https://qiita.com/taka_yayoi/items/ba8b412758758f5febc2#databricks%E3%81%A7%E5%88%A9%E7%94%A8%E3%83%AD%E3%82%B0%E3%82%92%E5%88%86%E6%9E%90%E3%81%99%E3%82%8B)をご覧ください。

# Terraformを用いた設定の自動化

[databricks\_mws\_log\_delivery](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/mws_log_delivery)リソースを活用することで、利用量ログデリバリーを自動で設定するために[Databricks Terraformプロバイダー](https://qiita.com/taka_yayoi/items/691ee4909b0961de5ad1)を使用することができます。以下に、利用量と監査ログデリバリーのエンドツーエンドのサンプルを示します。


```
variable "databricks_account_id" {
  description = "Account ID. You can get your account ID in the bottom left corner of the account console. See https://accounts.cloud.databricks.com"
}

resource "aws_s3_bucket" "logdelivery" {
  bucket = "${var.prefix}-logdelivery"
  acl    = "private"
  versioning {
    enabled = false
  }
  force_destroy = true
  tags = merge(var.tags, {
    Name = "${var.prefix}-logdelivery"
  })
}

resource "aws_s3_bucket_public_access_block" "logdelivery" {
  bucket             = aws_s3_bucket.logdelivery.id
  ignore_public_acls = true
}

data "databricks_aws_assume_role_policy" "logdelivery" {
  external_id = var.databricks_account_id
  for_log_delivery = true
}

resource "aws_iam_role" "logdelivery" {
  name               = "${var.prefix}-logdelivery"
  description        = "(${var.prefix}) UsageDelivery role"
  assume_role_policy = data.databricks_aws_assume_role_policy.logdelivery.json
  tags               = var.tags
}

data "databricks_aws_bucket_policy" "logdelivery" {
  full_access_role = aws_iam_role.logdelivery.arn
  bucket           = aws_s3_bucket.logdelivery.bucket
}

resource "aws_s3_bucket_policy" "logdelivery" {
  bucket = aws_s3_bucket.logdelivery.id
  policy = data.databricks_aws_bucket_policy.logdelivery.json
}

resource "databricks_mws_credentials" "log_writer" {
    account_id       = var.databricks_account_id
    credentials_name = "Usage Delivery"
    role_arn         = aws_iam_role.logdelivery.arn
}

resource "databricks_mws_storage_configurations" "log_bucket" {
    account_id                 = var.databricks_account_id
    storage_configuration_name = "Usage Logs"
    bucket_name                = aws_s3_bucket.logdelivery.bucket
}

resource "databricks_mws_log_delivery" "usage_logs" {
    account_id = var.databricks_account_id
    credentials_id = databricks_mws_credentials.log_writer.credentials_id
    storage_configuration_id = databricks_mws_storage_configurations.log_bucket.storage_configuration_id
    delivery_path_prefix = "billable-usage"
    config_name = "Usage Logs"
    log_type = "BILLABLE_USAGE"
    output_format = "CSV"
}

resource "databricks_mws_log_delivery" "audit_logs" {
    account_id = var.databricks_account_id
    credentials_id = databricks_mws_credentials.log_writer.credentials_id
    storage_configuration_id = databricks_mws_storage_configurations.log_bucket.storage_configuration_id
    delivery_path_prefix = "audit-logs"
    config_name = "Audit Logs"
    log_type = "AUDIT_LOGS"
    output_format = "JSON"
}
```

### Databricks 無料トライアル

[Databricks 無料トライアル](https://databricks.com/jp/try-databricks)