LogEvents APIを使用したイベント・ログのアップロード

LogEvents APIを介してイベント・ログをOracle Logging Analyticsエンドポイントにプッシュする場合は、次に示すステップに従います。

JSONの事前定義済ペイロード形式を使用して、1つ以上のイベントをアップロードできます。さらに、APIはGZIPおよびZIPアーカイブ形式をサポートしています。
各JSONの最大許容サイズは2 MBです。ただし、アップロード・リクエストには、ZIPの形式で最大100までの複数のJSONファイルを含めることができます。
ログ・グループは、リクエストの範囲で適用される必須のリクエスト・パラメータです。ログ・セットはオプション・パラメータであり、大量のログ・データ(TBなど)に毎日必要になる場合があります。

REST APIを使用してRAWログ・ファイルのアップロードを実行するステップは、オンデマンドでのログのアップロードを参照してください。

前提条件:

新しいログ・ソースまたはログ・フォーマットに一致するOracle定義のログ・ソースのログ・ソース名。Oracle定義ソースおよびソースの作成を参照してください。
REST APIを使用してアップロードを実行するには、ソースのタイプが「システム・イベント・メッセージ(Syslog)」、「ファイル」または「Oracle診断ログ(ODL)」である必要があります。
ログのアクセス制御を提供するログ・グループのOCID。ログを格納するログ・グループの作成を参照してください。
オプションで、アップロードするログをエンティティにマップする場合は、そのエンティティのOCID。ログ出力リソースを表すエンティティの作成を参照してください。

トピック:

イベント・ログのアップロードに必要な権限

ユーザーがアップロード操作を実行できるようにするには、アップロード・タスクの実行に必要な権限のみを選択的に付与するか、個々のリソース・タイプ権限を付与するか、より広範な集計レベルの権限を付与します。そのため、ユースケースに応じて、次に示す3つのポリシー・ステートメントの任意のセットを選択できます。

次のIAMポリシー・ステートメントは、アップロードのためにユーザー・グループに特定の権限を付与するためのものです:

allow group <group_name> to {LOG_ANALYTICS_LOG_GROUP_UPLOAD_LOGS} in compartment <log_group_compartment>

次のIAMポリシー・ステートメントは、アップロードの個々のリソース・タイプのレベルで権限を付与するためのものです:

allow group <group_name> to use loganalytics-log-group in compartment <log_group_compartment>

一方、次のIAMポリシー・ステートメントは、アップロードのOracle Logging Analytics集約リソース・レベルで権限を提供するためのものです:

allow group <group_name> to use loganalytics-resources-family in tenancy/compartment

前述のすべてのポリシー・ステートメントのgroup_nameは、必要な権限を付与する必要があるユーザー・グループを参照します。

イベント・ログをアップロードするためのAPI

REST APIおよび署名リクエストの使用の詳細は、REST APIおよびセキュリティ資格証明を参照してください。

uploadLogEventsFile APIドキュメントについては、ログ・アナリティクスAPI - uploadLogEventsFileを参照してください。

REST APIを使用してアップロードを実行するには、ホストで次のコマンドを実行します:

oci log-analytics upload upload-log-events-file --file <Json_Event_File_Path> --log-group-id <Log_Group_OCID> --namespace-name <Tenancy_Namespace_Name> --payload-type <Payload_Type>

前述のcurlコマンドでは、

Json_Event_File_Path: JSONイベント・ファイルのパス。JSONイベント・ファイルの形式および例の詳細は、LogEvents APIを使用してアップロードするイベント・ファイル形式を参照してください。
Tenancy_Namespace_Name: リクエストに使用されるOracle Logging Analyticsネームスペース。
Log_Group_OCID: アップロードされたログがOracle Logging Analyticsに格納されるログ・グループのOCID。
Payload_Type: デフォルトはJSONです。使用可能な値は、JSON、GZIP、ZIPです。
Log_Set: アップロードされたログに関連付けるログ・セット。このパラメータはオプション。

LogEvents APIを使用してアップロードするイベント・ファイル形式

JSONペイロードの一般的な形式は次のとおりです。

{
    "metadata":{ ----------------------------------------> Global (file level) metadata section to send additional metadata in field value pair format. The fields should be valid Logging Analytics Fields
        "Field1":"Value1",
        "Field2":"Value2",
        "FieldN":"ValueN"
    },
    "logEvents":
    [ ---------------------------------------------------> Group the events (logRecords) that belong to the same logSourceName, entityId, logPath and metadata
        {
            "metadata":{ --------------------------------> Group level metadata section
                "FieldA”:”ValueA”,
                "FieldB”:”ValueB”,
                "FieldN":"ValueN"
            },
            "entityId”:”<EntityOCID>“, -------------------> Logging Analytics Entity OCID
            "logSourceName”:”<LogSourceName>”, -----------> Logging Analytics LogSource Name (Mandatory)
            "logPath”:”<LogPath>”, -----------------------> logPath or logFileName to associate the log records with.
            "logRecords": -------------------------------> Array of logRecords/logEntries (Mandatory)
            [
                "logRecord1", ---------------------------> String representation of logRecord. In case the logRecord is of JSON type, it has to be encoded.
                "logRecord2",
                "logRecordN"
            ]
        },
        {            …            …            …       }
    ]
}

ノート

メタデータ・セクションは、実際のログ・レコードに含まれない情報でログをエンリッチするためのものです。

次に、JSONペイロードの例を示します。

{
    "metadata":{
        "Error ID":"0",
        "Environment":"dev",
        "Client Host Region":"IST"
    },
    "logEvents":
    [
        {
            "metadata":{
                "Error ID":"1",
                "Environment":"prod",
                "Client Host Region":"PST"
            },
            "entityId":"ocid1.loganalyticsentity.oc1.iad.amaaaaa...........",
            "logSourceName":"Linux Syslog Logs",
            "logPath":"/var/log/messages",
            "logRecords":
            [
                “Oct 20 2023 04:02:37 hostA syslogd 1.4.1: restart.",
                “Oct 20 2023 04:02:38 hostB syslogd 1.4.1: shutdown."
            ]
        }
    ]
}

Oracle Cloud Infrastructureドキュメント

イベント・ログのアップロードに必要な権限

イベント・ログをアップロードするためのAPI

LogEvents APIを使用してアップロードするイベント・ファイル形式