管理 Logpush 作业
IBM Cloud® Internet Services 企业级计划可以访问、DNS和Range请求的详细日志,以及其域的防火墙事件。HTTP 这些日志有助于调试和分析,尤其是在与其他数据源(如原点的入口或应用服务器日志)相结合时。
准备工作
在使用用户界面创建Logpush任务之前,请查看以下信息并满足所有前提条件:
-
目前,CIS 用户界面支持以下目的地:
- IBM Cloud Logs
- Cloud Object Storage
- Splunk
-
在使用Logpush之前,请务必 启用日志保留功能。
-
如果使用 Cloud Object Storage,您必须拥有一个 Cloud Object Storage 实例,且该实例的存储桶具有对象写入器访问权限,该权限已授予 IBM Cloud 账户
cislogp@us.ibm.com
。 这样,CIS 就可以将请求日志写入 Cloud Object Storage 存储桶。 -
来自 Logpush 的数据与来自 Logpull 的数据相同。 然而,与Logpull(允许您下载请求日志)不同,Logpush(允许您将请求日志推送到目标位置)。
-
DNS、范围和防火墙事件日志不包含在 HTTP / HTTPS 日志中,需要单独处理。 这些工作可以发送到同一个目的地。 但是,当使用 Cloud Object Storage 时,您需要指定不同的路径。
-
Logpush使用 Cloud Object Storage 的公开可访问 HTTPS 端点,确保日志数据在传输过程中得到加密。
-
当发送日志到 Splunk 时,CIS 会检查IP地址的可访问性和端口,然后验证 HTTP 接收日志源的证书。 如果所有参数都有效,则创建一个Logpush。 然后,Logpush开始向 HTTP 事件收集器( Splunk )发送事件。
-
如果您的目的地未得到 CIS 的明确支持,则Logpush仍可通过自定义 HTTP 目的地访问。 这包括您自己的自定义 HTTP 日志服务器。
为避免出错,请确保目标地址可以接受名为
test.txt.gz
的gzipped文件上传,其中包含压缩内容{"content":"tests"}
。 -
使用 Cloud Object Storage 时,您必须在创建Logpush作业后验证所有权。 这项任务将在以下程序中描述。
在控制台中创建 Logpush 作业
要在控制台中创建 Logpush 作业,请按照以下步骤操作:
-
选择 “账户” > “日志”,然后点击 “创建”。
-
选择服务:
- 从可用选项中选择所需的服务类型。
- 选择数据集类型。
- 可选:输入描述和名称。
- 选择下一步。
-
配置目的地:
- IBM Cloud Logs
-
输入 IBM Cloud 日志实例ID、实例区域和API密钥(用户管理)。
需要 IBM Cloud 日志实例所在账户的 API 密钥。 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API 密钥可通过使用 更新日志推送作业 API 进行轮换。
对于 IBM Cloud 日志服务,用户或服务ID必须被授予发送者 IAM角色。
- Cloud Object Storage
-
输入 Cloud Object Storage 实例、存储桶信息(名称和区域)以及存储桶路径(可选)。 然后将日志整理到每日文件夹中(可选)。
Cloud Object Storage 的终点值必须唯一。 建议使用桶状路径以避免冲突。
- Splunk
- 输入 Splunk 终端、频道ID和认证令牌。
您可以选择使用不安全的验证方式,但并不推荐这样做。
- 自定义 HTTP 目的地
-
输入您的 HTTP 终端。
请确保端点已正确进行 URL 编码,且任何必要的请求头已添加为 URL 参数,格式为“header_*”(例如
header_Authorization
)。
-
仅限 Cloud Object Storage 职位,请验证所有权。 为此,请下载您存储桶中的文件,然后将令牌粘贴到所有权令牌文本区域中。 然后,单击下一步。
您可以从“故障排除”部分重新发送文件,如果文件桶路径不正确,也可以返回上一步。
-
选择日志字段:
-
验证 Logpush 详细信息是否正确。
-
从“时间戳格式”和“频率”菜单中选择Logpush设置。
-
选择是否启用Logpush作业,将启用开关切换到“开启” 即可。
-
选择要包含在Logpush任务中的日志字段。
您可以使用切换按钮选择所有字段或展开所有字段。 您也可以恢复到默认设置。
-
点击 “完成” 创建您的Logpush任务。
-
从命令行界面创建Logpush任务
您可以使用 ibmcloud cis logpush-job-create
CLI创建Logpush任务。
要为特定域创建Logpush作业并启用该作业,请运行以下命令:
ibmcloud cis logpush-job-create DNS_DOMAIN_ID --destination PATH --name JOB_NAME --fields all --enable true
其中:
-destination
:指定目标路径。 支持的目的地路径如下:
IBM Cloud Logs |
---|
ibmcl://<INSTANCE_ID>.ingress.<REGION>.logs.cloud.ibm.com/logs/v1/singles?ibm_api_key=<IBM_API_KEY>
例如需要设置 日志实例的账户的 API 密钥。 IBM Cloud 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API 密钥可通过使用更新日志推送作业 API 进行轮换。 重要: 用户或服务 ID 必须在 IBM Cloud 日志服务上被授予发送方 IAM 角色。 |
Cloud Object Storage |
---|
cos://<BUCKET_OBJECT_PATH>?region=<REGION>&instance-id=<IBM_ClOUD_OBJECT_STORAGE_INSTANCE_ID>
例如: |
自定义 HTTP |
---|
https://<HOSTNAME>?header_Authorization=Basic%20REDACTED&tags=host:<DOMAIN_NAME>,dataset:<LOGPUSH_DATASET>
例如: |
--name
:指定 Logpush 任务名称。
--fields
:指定要包含在日志文件中的日志字段列表。 使用逗号分隔多个字段。 使用 ibmcloud cis logpush-available-fields DNS_DOMAIN_ID --dataset DATASET
命令可获得可用日志字段的完整列表,或使用 all
命令将所有可用字段包含在日志文件中。
--enable
:是启用或禁用 Logpush 作业的标志。 有效值为 true
或 false
(默认值)。
Cloud Object Storage:验证所有权
创建Logpush任务将日志发送至 Cloud Object Storage 后,您必须验证所有权。
当挑战令牌写入指定 Cloud Object Storage 存储桶中的文件时,请按照以下步骤操作:
- 从您的 Cloud Object Storage 存储空间下载文件并打开。
- 从文件中复制挑战令牌,并将其粘贴到命令提示符中,以解决所有权挑战。
在 CIS 验证所有权挑战后,Logpush作业成功创建。 然后,该任务将每30秒或达到100,000条记录时(以先到者为准)将请求日志推送到您的 Cloud Object Storage 存储桶中。 请注意,在30秒内或每10万条记录中可能会推送多个文件。
您还可以使用桶路径中的 {DATE}
令牌将 Logpush 日志整理到每日文件夹中。 例如: cos://mybucket/cislog/{DATE}?region=us-south&instance-id=c84e2a79-ce6d-3c79-a7e4-7e7ab3054cfe
命令示例
CLI示例支持的目的地:
- IBM Cloud Logs
-
示例
ibmcloud cis logpush-job-create 601b728b86e630c744c81740f72570c3 --destination "ibmcl://604a309c-585c-4a42-955d-76239ccc1905.ingress.us-south.logs.cloud.ibm.com/logs/v1/singles?ibm_api_key=xxxxxxxx" --name logpushJobGen --enable true --fields RayID --dataset http_requests --frequency high -i 1a9174b6-0106-417a-844b-c8eb43a72f63
- Cloud Object Storage
-
示例
ibmcloud cis logpush-job-create 31984fea73a15b45779fa0df4ef62f9b --destination cos://cis-test-bucket/logs?region=us&instance-id=f75e6d90-4212-4026-851c-d572071146cd --name logpushcreate --enable true --fields all --timestamps rfc3339 --dataset http_requests --frequency low -i cis-demo --output JSON
- 自定义 HTTP
-
示例
ibmcloud cis logpush-job-create 601b728b86e630c744c81740f72570c3 --destination https://logs.example.com?header_Authorization=a64VuywesDu5Aq" --name logpushJobGen --enable true --fields RayID --dataset http_requests --frequency high -i 1a9174b6-0106-417a-844b-c8eb43a72f63
使用 API 创建 Logpush 作业
当使用 IBM Cloud、Cloud Object Storage 或 Splunk 时,您可以使用 创建Logpush作业API 来创建Logpush作业。
使用API获取数据集的可用日志字段
日志字段可以在Logpush作业的 logpull_options
中指定,以自定义发送到目的地的内容。 要获取Logpush数据集的可用日志字段,请按照以下步骤操作:
-
使用正确的变量设置 API 环境。
-
在变量中存储以下值,以便在 API 命令中使用:
CRN
:服务实例的完整 URL 编码CRN。ZONE_ID
:域名 ID。DATASET
:正在检查Logpush数据集。http_requests
,range_events
,dns_logs
,firewall_events
中的一个。 -
启动所有变量后,创建 Logpush 作业:
curl -X GET https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/datas/$DATASET/fields \ --header "Content-Type: application/json" \ --header "X-Auth-User-Token: Bearer $IAM_TOKEN"'
创建一个Logpush任务,将日志发送到您的目的地
要创建一个目标为( IBM Cloud 日志、Cloud Object Storage 或 Splunk )的 Logpush 作业,请按照以下步骤操作:
-
使用正确的变量设置 API 环境。
-
在变量中存储以下值,以便在 API 命令中使用:
CRN
:服务实例的完整 URL 编码云资源名称(CRN)。ZONE_ID
:域名 ID。--request body
:创建Logpush作业正文的信息(logpush_job_DESTINATION_req
),其中DESTINATION
为以下值之一:IBM Cloud 记录目的地 IBM Cloud Logs ibmcl
:用于标识推送数据的 IBM Cloud 日志实例的信息。ibmcl
对象中的字段包括:instance_id
: IBM Cloud 日志实例的ID。region
: IBM Cloud 日志实例的区域(例如,us-south
)。api_key
:需要设置 IBM Cloud 日志实例的帐户的API密钥。 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API密钥可通过更新Logpush作业API 进行轮换。
重要提示: 必须在 IBM Cloud 日志服务上为用户或服务ID授予发送者I AM角色。
ibmcl_names
: 可选字段,用于自定义 IBM Cloud 日志中使用的应用程序和子系统名称。ibmcl_names
对象中的字段包括:application_name
:作业的自定义应用程序名称。subsystem_name
:作业的自定义子系统名称。
Cloud Object Storage 目的地 Cloud Object Storage cos
:用于识别数据推送的 Cloud Object Storage 存储桶的信息。cos
对象中的字段包括:bucket_name
:发送日志的COS存储桶名称(例如:cos-bucket001
)。region
: Cloud Object Storage 实例的区域(例如:us-south
)。id
:COS实例的ID。
Splunk 目的地 Splunk splunk
:用于识别 Splunk HTTP Event Collector (HEC)的信息,数据将推送到该位置。splunk
对象中的字段包括:endpoint_url
: URL 的 Splunk HEC。channel_id
:用于唯一标识日志推送的随机GUID。skip_verify
:用于跳过 HTTP 事件收集器证书验证的布尔标志。 仅当HEC使用自签名证书时,才将此设置为true
。source_type
: Splunk 源类型(例如:cloudflare:json
)。auth_token
: Splunk 授权令牌。
自定义 HTTP 目的地 自定义 HTTP destination_conf
:用于配置自定义 HTTP 目标的信息,数据将推送到该目标。 日志推送(Logpush)可以使用以header_
为前缀的查询参数指定标题(例如:header_Authorization=XXXX
)。name
:Logpush 工作的名称。enabled
:工作是否已启用。true
或false
。logpull_options
:配置字符串。 例如,fields=RayID,ZoneID×tamps=rfc3339
。dataset
:提取的数据集。http_requests
,dns_logs
,range_events
,firewall_events
中的一个。frequency
: CIS 向目的地发送成批日志的频率。high
或low
。 -
启动所有变量后,创建 Logpush 作业:
IBM Cloud Logs
curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \ --header "Content-Type: application/json" \ --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \ --data '{ "ibmcl": { "instance_id": "f8k3309c-585c-4a42-955d-76239cccf8k3", "region": "us-south", "api_key": "f8k3NQI22dPwNVCcmS62YFL1tm9vaehY6C9jxdtnf8k3" }, "ibmcl_names": { "application_name": "cis-edge-logs", "subsystem_name": "stage-firewall-logs" } "dataset": "http_requests", "enabled": true, "logpull_options": "fields=RayID,ZoneID×tamps=rfc3339", "name": "CIS-Edge-Requests", "frequency": "low" }'
Cloud Object Storage
curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \ --header "Content-Type: application/json" \ --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \ --data '{ "cos": { "bucket_name": "example_bucket", "path": "temp/", "id": "cos_instance_id", "region": "us-east" }, "dataset": "firewall_events", "enabled": false, "name": "CIS-Firewall-COS", "frequency": "low", "logpull_options": "fields=RayID,ZoneID×tamps=rfc3339", "ownership_challenge": "xxxxxxx" }'
Splunk
curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \ --header "Content-Type: application/json" \ --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \ --data '{ "splunk": { "endpoint_url": "example.splunkcloud.com:8088/services/collector/raw", "channel_id": "def3c136-7a01-4655-b17f-8e25a780ef2c", "skip_verify": false, "source_type": "cloudflare:json", "auth_token": "Splunk fake3585-0f38-4d62-8b43-c4b78584fake" }, "dataset": "http_requests", "enabled": true, "name": "CIS-Splunk-Logpush", "frequency": "high", "logpull_options": "fields=RayID,CacheResponseBytes,CacheResponseStatus,CacheCacheStatus×tamps=rfc3339" }'
自定义 HTTP
curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \ --header "Content-Type: application/json" \ --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \ --data '{ "destination_conf": "https://logs.example.com?header_Authorization=a64VuywesDu5Aq", "dataset": "http_requests", "enabled": true, "name": "CIS-Custom-Logpush", "frequency": "high", "logpull_options": "fields=RayID,CacheResponseBytes,CacheResponseStatus,CacheCacheStatus×tamps=rfc3339" }'