サポートされている宛先にログをルーティングする

このドキュメントでは、 Google Cloud プロジェクトで発生したログエントリをサポートされている宛先にルーティングするログシンクを作成して管理する方法について説明します。

シンクは書き込みアクションを実行するため、宛先への書き込みが許可されている必要があります。宛先がシンクと同じプロジェクト内のログバケットの場合、シンクは自動的に承認されます。他のすべての宛先では、宛先へのデータの書き込みに必要な権限が付与されているサービス アカウントにシンクを接続する必要があります。

サービス アカウントが必要な場合は、Cloud Logging によって自動的に作成、管理されます。ただし、サービス アカウントに付与される権限の変更が必要になる場合があります。Logging によって作成されたサービス アカウントを使用する必要はありません。複数のプロジェクトのシンクによって使用されるサービス アカウントを作成して管理できます。詳細については、ユーザー管理のサービス アカウントでログシンクを構成するをご覧ください。

概要

このページでは、シンクの作成方法と、 Google Cloud コンソールまたは API の使用時に表示されるオプションの構成方法について説明します。

シンクは、特定の Google Cloud リソース（ Google Cloud プロジェクト、請求先アカウント、フォルダ、組織）に属します。リソースがログエントリを受信すると、そのリソースのすべてのシンクがログエントリを処理します。ログエントリがシンクのフィルタと一致すると、ログエントリはそのシンクの宛先に転送されます。

通常、シンクはリソースで発生したログエントリのみを転送します。フォルダと組織の場合は、フォルダまたは組織で発生したログエントリと、そのフォルダまたは組織に含まれるリソースを転送する集約シンクを作成できます。このドキュメントでは、集約シンクについては説明しません。詳細については、集約シンクの概要をご覧ください。

シンクの作成と管理には、 Google Cloud コンソール、Cloud Logging API、Google Cloud CLI を使用できます。次に示す理由から Google Cloud コンソールの使用をおすすめします。

  • シンクの宛先は、シンクを作成するフローの一部として構成できます。
  • シンクのフィルタに一致するログエントリをプレビューできます。
  • 認可手順の一部が簡素化されます。

ログシンクを表示し、管理する方法については、このドキュメントのシンクを管理するのセクションをご覧ください。

選択できる宛先

シンクの宛先は、シンクとは異なるリソースに配置できます。たとえば、ログシンクを使用して、あるプロジェクトのログを別のプロジェクトに保存されているログバケットにルーティングできます。

次の宛先がサポートされています。

Google Cloud プロジェクト

宛先プロジェクトのログシンクでログエントリを再ルーティングする場合、またはインターセプト集約シンクを作成した場合は、この宛先を選択します。シンクの宛先であるプロジェクトのログシンクは、プロジェクトを除くサポートされている任意の宛先にログエントリを再ルーティングできます。

ログバケット
Cloud Logging によって管理されるリソースにログデータを保存する場合は、この宛先を選択します。ログバケットに保存されたログデータは、ログ エクスプローラなどのサービスを使用して確認および分析できます。
Pub/Sub トピック
Google Cloud からログデータをエクスポートし、サードパーティ統合を使用する場合は、この宛先を選択します。ログエントリは JSON 形式にフォーマットされ、Pub/Sub トピックにルーティングされます。

宛先の制限事項

このセクションでは、宛先固有の制限事項について説明します。

  • ログシンクの宛先が Google Cloud プロジェクトの場合、次の制限が適用されます。

    • 1 ホップの上限があります。
    • _Required ログシンクのフィルタに一致するログエントリは、宛先プロジェクトで生成された場合にのみ、宛先プロジェクトの _Required ログバケットにルーティングされます。
    • ログエントリのリソース階層にある集約シンクのみがログエントリを処理します。

    たとえば、プロジェクト A のログシンクの宛先がプロジェクト B である場合、次のようになります。

    • 1 ホップの制限により、プロジェクト B のログシンクはログエントリをプロジェクト Google Cloud に再ルーティングできません。
    • プロジェクト B の _Required ログバケットには、プロジェクト B で発生したログエントリのみが保存されます。このログバケットには、プロジェクト A で発生したログエントリなど、他のリソースで発生したログエントリは保存されません。
    • プロジェクト A とプロジェクト B のリソース階層が異なる場合、プロジェクト A のログシンクがプロジェクト B にルーティングするログエントリは、プロジェクト B のリソース階層の集約シンクに送信されません。
    • プロジェクト A とプロジェクト B に同じリソース階層がある場合、ログエントリはその階層の集約シンクに送信されます。ログエントリが集約シンクによってインターセプトされなかった場合、ログルーターでログエントリがプロジェクト A のシンクに送信されます。

始める前に

このドキュメントでは、Google Cloud プロジェクト レベルでシンクを作成、管理する手順について説明します。組織、フォルダ、請求先アカウントで発生したログエントリを転送するシンクも同じ手順で作成できます。

作業を始める前に、次のことを行います。

  1. Enable the Cloud Logging API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  2. Google Cloud プロジェクトに、ログ エクスプローラで表示できるログエントリがあることを確認します。

  3. シンクの作成、変更、削除を行うために必要な権限を取得します。プロジェクトに対するログ構成書き込み（roles/logging.configWriter）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

    必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

    IAM ロールの付与については、Logging のアクセス制御ガイドをご覧ください。

  4. サポート対象の宛先にリソースがあるか、作成できる。

    ログエントリを宛先に転送するには、シンクを作成する前に宛先が存在している必要があります。宛先は、どの組織のどのGoogle Cloud プロジェクトにも作成できます。

  5. シンクを作成する前に、シンクの宛先に適用される制限事項を確認します。詳細については、このドキュメントの宛先の制限事項をご覧ください。

  6. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    Google Cloud CLI をインストールし、連携 ID を使用して gcloud CLI にログインします。 ログイン後、次のコマンドを実行して Google Cloud CLI を初期化します。 

    gcloud init

    REST

    このページの REST API サンプルをローカル開発環境で使用するには、gcloud CLI に指定した認証情報を使用します。

      Google Cloud CLI をインストールし、連携 ID を使用して gcloud CLI にログインします。 ログイン後、次のコマンドを実行して Google Cloud CLI を初期化します。 

      gcloud init

    詳細については、 Google Cloud 認証ドキュメントの REST を使用して認証するをご覧ください。

    シンクを作成する

    このセクションでは、 Google Cloud プロジェクトにシンクを作成する方法について説明します。1 つの Google Cloud プロジェクトに最大 200 個のシンクを作成できます。転送されるログエントリの数量を確認するには、logging.googleapis.com/exports/ 指標を表示します。

    Logging クエリ言語を使用して、含めるログエントリに一致するフィルタ式を作成します。機密情報はシンクフィルタに記述しないでください。シンクフィルタはサービスデータとして扱われます。

    クエリに複数のステートメントが含まれている場合は、それらのステートメントの結合方法を指定するか、Cloud Logging がステートメント間に結合制約 AND を暗黙的に追加することを許可します。たとえば、クエリまたはフィルタ ダイアログに resource.type = "gce_instance" と severity >= "ERROR" の 2 つのステートメントが含まれているとします。実際のクエリは resource.type = "gce_instance" AND severity >= "ERROR" です。Cloud Logging は、論理和制約（OR）と論理積制約（AND）の両方をサポートしています。OR ステートメントを使用する場合は、句を括弧でグループ化することをおすすめします。

    シンクを作成する方法は次のとおりです。

    コンソール

    1. Google Cloud コンソールで、[ログルーター] ページに移動します。

      [ログルーター] に移動

      検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。

    2. ログエントリの転送元の Google Cloud プロジェクトを選択します。

      たとえば、Project-A というプロジェクトから Project-B というプロジェクトのログバケットにデータアクセスのログエントリを転送する場合は、Project-A を選択します。

    3. [シンクを作成] を選択します。

    4. [シンクの詳細] パネルで、次の詳細を入力します。

      • シンクの名前: シンクの識別子を指定します。シンクを作成した後はシンク名を変更できませんが、シンクを削除して新しいシンクを作成することはできます。

      • シンクの説明（省略可）: シンクの目的またはユースケースについて記述します。

    5. [シンクの宛先] パネルで、[シンクサービスの選択] メニューを使用して、シンクのサービスと宛先を選択します。次のいずれかを行います。

      • ログエントリを同じGoogle Cloud プロジェクト内のサービスに転送するには、次のいずれかのオプションを選択します。

        • Pub/Sub トピック: 転送されたログエントリを受信するトピックを選択または作成します。

      • ログエントリを別の Google Cloud プロジェクトにルーティングする場合は、[Google Cloud プロジェクト] を選択して、宛先の完全修飾名を入力します。

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • ログエントリを別のGoogle Cloud プロジェクトのサービスにルーティングするには、次の手順で操作します。

        1. [その他のリソース] を選択します。
        2. 宛先の完全修飾名を入力します。構文については、宛先パスの形式をご覧ください。

    6. 含めるログエントリを指定します。

      1. [シンクに含めるログの選択] パネルに移動します。

      2. [一致フィルタの作成] フィールドに、含めるログエントリに一致するフィルタ式を入力します。フィルタの構文の詳細については、Logging のクエリ言語をご覧ください。

        フィルタを設定しない場合は、選択したリソースのすべてのログエントリが宛先に転送されます。

        たとえば、データアクセスのすべてのログエントリを Logging バケットに転送するには、次のフィルタを使用します。

        log_id("cloudaudit.googleapis.com/data_access") OR log_id("externalaudit.googleapis.com/data_access")

        フィルタの長さは 20,000 文字以下にする必要があります。

      3. 正しいフィルタを入力したことを確認するには、[ログをプレビュー] を選択します。フィルタが事前に入力された状態で、ログ エクスプローラが新しいタブで開きます。

    7. （省略可）除外フィルタを構成して、含まれるログエントリの一部を除外します。

      1. [シンクに含めないログの選択] パネルに移動します。

      2. [除外フィルタ名] フィールドに名前を入力します。

      3. [除外フィルタの作成] セクションで、除外するログエントリに一致するフィルタ式を入力します。sample 関数を使用して、除外するログエントリの一部を選択することもできます。

      シンクごとに最大 50 個の除外フィルタを作成できます。フィルタの長さは 20,000 文字以下にする必要があります。

    8. [シンクを作成] を選択します。

    9. シンクのサービス アカウントに、シンクの宛先にログエントリを書き込む権限を付与します。詳細については、宛先の権限を設定するをご覧ください。

    gcloud

    シンクを作成する方法は次のとおりです。

    1. 次の gcloud logging sinks create コマンドを実行します。

      gcloud logging sinks create SINK_NAME SINK_DESTINATION

      コマンドを実行する前に、次のように置き換えます。

      • SINK_NAME: ログシンクの名前。シンクの作成後に名前を変更することはできません。

      • SINK_DESTINATION: ログエントリの転送先となるサービスまたはプロジェクト。宛先パスの形式で説明されているように、SINK_DESTINATION に適切なパスを設定します。

        たとえば、シンクの宛先が Pub/Sub トピックの場合、SINK_DESTINATION は次のようになります。

        pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

      次のオプションも指定できます。

      • --log-filter: シンクに含めるログエントリに一致するフィルタを設定する場合には、このオプションを使用します。一致フィルタの値を指定しないと、このフィルタはすべてのログエントリと一致します。
      • --exclusion: シンクの転送から除外するログエントリに除外フィルタを設定するには、このオプションを使用します。sample 関数を使用して、除外するログエントリの一部を選択することもできます。このオプションは繰り返すことができますが、1 つのシンクに作成できる除外フィルタは 50 個までです。
      • --description: シンクの目的またはユースケースを記述する場合は、このオプションを使用します。

      たとえば、Logging バケットにシンクを作成する場合、コマンドは次のようになります。

      gcloud logging sinks create my-sink logging.googleapis.com/projects/myproject123/locations/global/buckets/my-bucket \
 --log-filter='logName="projects/myproject123/logs/matched"' --description="My first sink"

      Google Cloud CLI を使用してシンクを作成する方法については、gcloud logging sinks リファレンスをご覧ください。

    2. コマンドのレスポンスに "writerIdentity" というラベルの JSON キーが含まれている場合は、シンクのサービス アカウントに、シンクの宛先への書き込み権限を付与します。詳細については、宛先の権限を設定するをご覧ください。

      レスポンスに "writerIdentity" というラベルの JSON キーが含まれていない場合は、宛先の権限を設定する必要はありません。

    REST

    1. Google Cloud プロジェクトにロギングシンクを作成するには、Logging API で projects.sinks.create を使用します。LogSink オブジェクトで、メソッドのリクエストの本文に適切な必須値を指定します。

      • name: シンクの名前。シンクを作成した後にシンク名は変更できませんが、シンクを削除して新しいシンクを作成することはできます。

      • destination: ログエントリの転送先となるサービスと宛先。ログエントリを異なるプロジェクト、または別のプロジェクトの宛先に転送するには、宛先パスの形式で説明されているとおりに、destination フィールドに適切なパスを設定します。

        たとえば、シンクの宛先が Pub/Sub トピックの場合、destination は次のようになります。

        pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

    2. LogSink オブジェクトで、適切なオプション情報を指定します。

      • filter: シンクに含めるログエントリに一致するように filter フィールドを設定します。フィルタを設定しない場合、Google Cloud プロジェクトからのすべてのログエントリが宛先に転送されます。フィルタの長さは 20,000 文字以下にする必要があります。
      • exclusions: シンクから除外するログエントリに一致するように、このフィールドを設定します。sample 関数を使用して、除外するログエントリの一部を選択することもできます。シンクごとに最大 50 個の除外フィルタを作成できます。
      • description: シンクの目的やユースケースを記述する場合は、このフィールドを設定します。

    3. projects.sinks.create を呼び出して、シンクを作成します。

    4. API レスポンスに "writerIdentity" というラベルの JSON キーが含まれている場合は、シンクのサービス アカウントに、シンクの宛先への書き込み権限を付与します。詳細については、宛先の権限を設定するをご覧ください。

      API レスポンスに "writerIdentity" というラベルの JSON キーが含まれていない場合は、宛先の権限を設定する必要はありません。

    Logging API を使用してシンクを作成する方法については、LogSink リファレンスをご覧ください。

    エラー通知を受け取った場合は、転送とシンクのトラブルシューティングをご覧ください。

    宛先パスの形式

    ログエントリを別のプロジェクトのサービスに転送する場合は、シンクにサービスの完全修飾名を指定する必要があります。同様に、ログエントリを別の Google Cloud プロジェクトに転送する場合は、宛先プロジェクトの完全修飾名をシンクに指定する必要があります。

    • Cloud Logging ログバケット:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

    • 別の Google Cloud プロジェクト:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Pub/Sub トピック: 

      pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

    宛先の権限を設定する

    このセクションでは、シンクの宛先にログエントリを書き込むための Identity and Access Management 権限を Logging に付与する方法について説明します。Logging のロールと権限の完全なリストについては、アクセス制御をご覧ください。

    必要なサービス アカウントがすでに存在していない限り、Cloud Logging はシンクの作成時にリソースの共有サービス アカウントを作成します。基盤となるリソース内のすべてのシンクに同じサービス アカウントが使用されるため、サービス アカウントがすでに存在している場合があります。リソースには、 Google Cloud プロジェクト、組織、フォルダ、請求先アカウントがあります。

    シンクの書き込み ID は、そのシンクに関連付けられているサービス アカウントの ID です。ログエントリの発生元の Google Cloud プロジェクトのログバケットに書き込むシンクを除き、すべてのシンクには書き込み ID があります。後者の構成ではサービス アカウントは不要であるため、シンクの [書き込み ID] フィールドはコンソールで「None」と表示されます。API と Google Cloud CLI コマンドは書き込み ID を報告しません。

    次の手順は、プロジェクト、フォルダ、組織、請求先アカウントに適用されます。

    コンソール

    1. 宛先を含むGoogle Cloud プロジェクトに対するオーナー アクセス権があることを確認します。シンクの宛先に対するオーナー権限がない場合は、書き込み ID をプリンシパルとして追加するようプロジェクト オーナーに依頼します。

    2. 新しいシンクからシンクの書き込み ID（メールアドレス）を取得するには、次の操作を行います。

      1. Google Cloud コンソールで、[ログルーター] ページに移動します。

        [ログルーター] に移動

        検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。

      2. ツールバーで、シンクを含むプロジェクトを選択します。
      3. [ メニュー] を選択し、[シンクの詳細を表示する] を選択します。[シンクの詳細] パネルに書き込み ID が表示されます。

    3. writerIdentity フィールドの値にメールアドレスが含まれている場合は、次のステップに進みます。値が None の場合、シンクの宛先権限を構成する必要はありません。

    4. シンクの書き込み ID をクリップボードにコピーします。

      メールアドレスはプリンシパルを識別します。接頭辞 serviceAccount: はアカウントの種類を指定します。

    5. シンクの書き込み ID で指定されたプリンシパルに、エクスポート先にログデータを書き込む権限を付与します。

      1. Google Cloud コンソールで [IAM] ページに移動します。

        [IAM] に移動

        このページを検索バーで検索する場合は、小見出しが「IAM と管理」の結果を選択します。

      2. ツールバーで、選択したプロジェクトが宛先を保存するプロジェクトか、シンクの宛先であることを確認します。たとえば、宛先がログバケットの場合は、ログバケットを保存するプロジェクトがツールバーに表示されていることを確認します。

      3. [アクセスを許可] をクリックします。

      4. シンクの書き込み ID で指定されたプリンシパルに、ログシンクの宛先に基づいて IAM ロールを付与します。

    gcloud

    1. 宛先を含むGoogle Cloud プロジェクトに対するオーナー アクセス権があることを確認します。シンクの宛先に対するオーナー権限がない場合は、書き込み ID をプリンシパルとして追加するようプロジェクト オーナーに依頼します。

    2. シンク内の writerIdentity フィールドからサービス アカウントを取得します。

      gcloud logging sinks describe SINK_NAME

    3. 権限を変更するシンクを探し、シンクの詳細の行に writerIdentity が含まれている場合は、次のステップに進みます。詳細に writerIdentity フィールドが含まれていない場合、シンクの宛先権限を構成する必要はありません。

      サービス アカウントの書き込み ID は次のようになります。

      serviceAccount:service-123456789012@gcp-sa-logging.

    4. gcloud projects add-iam-policy-binding コマンドを呼び出して、エクスポート先にログデータを書き込む権限をシンクの書き込み ID に付与します。

      次のコマンドを使用する前に、次のように置き換えます。

      • PROJECT_ID: プロジェクトの ID。ログシンクの宛先を保存するプロジェクトを指定します。宛先がプロジェクトの場合は、そのプロジェクトを指定します。
      • PRINCIPAL: ロールを付与するプリンシパルの ID。通常、プリンシパル ID の形式は PRINCIPAL-TYPE:ID です。例: PRINCIPAL に使用できる形式の一覧については、プリンシパル ID をご覧ください。

      • ROLE: IAM ロール。ログシンクの宛先に基づいて、シンクの書き込み ID に IAM ロールを付与します。

      gcloud projects add-iam-policy-binding コマンドを実行します。

      gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

    REST

    サービス アカウントにロールを付与する場合は、 Google Cloud コンソールまたは Google Cloud CLI を使用することをおすすめします。

    フィルタの例

    次に、シンクの作成時に特に役立つフィルタの例をいくつか示します。一致フィルタと除外フィルタの作成時に役立つその他の例については、サンプルクエリをご覧ください。

    _Default シンクフィルタを復元する

    _Default シンクのフィルタを編集した場合は、このシンクの構成を元に戻すことをおすすめします。作成時に、_Default シンクは次の一致フィルタと空の除外フィルタで構成されます。

      NOT log_id("cloudaudit.googleapis.com/activity") AND NOT \
  log_id("externalaudit.googleapis.com/activity") AND NOT \
  log_id("cloudaudit.googleapis.com/system_event") AND NOT \
  log_id("externalaudit.googleapis.com/system_event") AND NOT \
  log_id("cloudaudit.googleapis.com/access_transparency") AND NOT \
  log_id("externalaudit.googleapis.com/access_transparency")

    Google Kubernetes Engine コンテナと Pod のログを除外する

    GKE システム namespaces の Google Kubernetes Engine コンテナと Pod のログエントリを除外するには、次のフィルタを使用します。

    resource.type = ("k8s_container" OR "k8s_pod")
resource.labels.namespace_name = (
"cnrm-system" OR
"config-management-system" OR
"gatekeeper-system" OR
"gke-connect" OR
"gke-system" OR
"istio-system" OR
"knative-serving" OR
"monitoring-system" OR
"kube-system")

    GKE システム logNames の Google Kubernetes Engine ノードのログエントリを除外するには、次のフィルタを使用します。

    resource.type = "k8s_node"
logName:( "logs/container-runtime" OR
"logs/docker" OR
"logs/kube-container-runtime-monitor" OR
"logs/kube-logrotate" OR
"logs/kube-node-configuration" OR
"logs/kube-node-installation" OR
"logs/kubelet" OR
"logs/kubelet-monitor" OR
"logs/node-journal" OR
"logs/node-problem-detector")

    サポート性

    Cloud Logging では、ログエントリを除外してログバケットへの保存を防ぐことができますが、サポートに役立つログエントリについては保持することを検討してください。これらのログエントリは、アプリケーションの問題のトラブルシューティングと特定に役立ちます。

    たとえば、GKE システムのログエントリは、クラスタで発生したイベントに対して生成されるため、GKE アプリケーションとクラスタのトラブルシューティングに役立ちます。これらのログエントリは、アプリケーション コードまたは基盤となる GKE クラスタがアプリケーション エラーの原因かどうかを特定するうえで役立ちます。GKE システムログには、Kubernetes API Server コンポーネントによって生成された Kubernetes 監査ロギングも含まれます。このログには、kubectl コマンドと Kubernetes イベントを使用して行われた変更が含まれます。

    次のステップ