Creating a Log Ingestion Configuration

Function

This API is used to create a log ingestion configuration.

URI

POST /v3/{project_id}/lts/access-config

Table 1 Path Parameters

Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain a project ID, see Obtaining the Account Tenant ID, Project Resource Set ID, Log Group ID, and Log Stream ID. Minimum: 32 Maximum: 32

Request Parameters

Table 2 Request header parameters

Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token obtained from IAM. For details about how to obtain a user token, see Obtaining a User Token. Minimum: 1000 Maximum: 2000
Content-Type	Yes	String	Set this parameter to application/json;charset=UTF-8. Minimum: 30 Maximum: 30

Table 3 Request body parameters

Parameter	Mandatory	Type	Description
access_config_name	Yes	String	Ingestion configuration name. It should match the regular expression: ^(?!.)(?!_)(?!.*?.$)[\u4e00-\u9fa5a-zA-Z0-9-_.]{1,64}$. Minimum: 1 Maximum: 64
access_config_type	Yes	String	Ingestion configuration type. AGENT: ECS access; K8S_CCE: CCE access
access_config_detail	Yes	AccessConfigDeatilCreate object	Access configuration details.
log_info	Yes	AccessConfigBaseLogInfoCreate object	Log information
host_group_info	No	AccessConfigHostGroupIdListCreate object	Host group information
access_config_tag	No	Array of accessConfigTag objects	Tag information. A tag key must be unique. Up to 20 tags are allowed.
binary_collect	No	Boolean	Binary collection.
log_split	No	Boolean	Log splitting.
cluster_id	No	String	Cluster ID

Table 4 AccessConfigDeatilCreate

Parameter	Mandatory	Type	Description
paths	No	Array of strings	Collection paths. A path must start with a slash (/), backslash (\), colon (:), or letter. A path cannot contain special characters (<>'| ") and cannot contain only slashes (/). A path cannot start with "/**" or "/*". Only one double asterisk (**) can be contained in a path. The container path and host path are mandatory for the CCE type and are not mandatory for the standard output.
black_paths	No	Array of strings	Collection path blacklist. A path must start with a slash (/), backslash (\), colon (:), or letter. A path cannot contain special characters (<>'| ") and cannot contain only slashes (/). A path cannot start with "/**" or "/*". Only one double asterisk (**) can be contained in a path.
format	Yes	AccessConfigFormatCreate object	Log format.
windows_log_info	No	AccessConfigWindowsLogInfoCreate object	Windows event logs.
stdout	No	Boolean	Standard output switch. This parameter is used only when logs are collected from CCE.
stderr	No	Boolean	Standard error switch. This parameter is used only when logs are collected from CCE.
pathType	No	String	Log collection from CCE. This parameter is used only when logs are collected from CCE.
namespaceRegex	No	String	Regular expression matching of Kubernetes namespaces. This parameter is used only when logs are collected from CCE.
podNameRegex	No	String	Regular expression matching of Kubernetes pods. This parameter is used only when logs are collected from CCE.
containerNameRegex	No	String	Regular expression matching of Kubernetes container names. This parameter is used only when logs are collected from CCE.
includeLabels	No	Map<String,String>	Container label trustlist. A maximum of 30 container labels can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
excludeLabels	No	Map<String,String>	Container label blocklist. A maximum of 30 container labels can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
includeEnvs	No	Map<String,String>	Environment variable trustlist. A maximum of 30 environment variable whitelists can be created. Key names must be unique. This parameter is used only when logs are collected from CCE.
excludeEnvs	No	Map<String,String>	Environment variable blocklist. A maximum of 30 environment variables can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
logLabels	No	Map<String,String>	Container label log tag. A maximum of 30 tags can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
logEnvs	No	Map<String,String>	Environment variable log tag. A maximum of 30 tags can be created. The key name must be unique. This parameter is used only when logs are collected from CCE.
includeK8sLabels	No	Map<String,String>	Kubernetes label trustlist. A maximum of 30 whitelists can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
excludeK8sLabels	No	Map<String,String>	Kubernetes label blocklist. A maximum of 30 blocklists can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.
logK8s	No	Map<String,String>	Kubernetes label log tag. A maximum of 30 tags can be created. The key names must be unique. This parameter is used only when logs are collected from CCE.

Table 5 AccessConfigFormatCreate

Parameter	Mandatory	Type	Description
single	No	AccessConfigFormatSingleCreate object	Single-line logs.
multi	No	AccessConfigFormatMutilCreate object	Multi-line logs.

Table 6 AccessConfigFormatSingleCreate

Parameter	Mandatory	Type	Description
mode	No	String	Single-line logs. system indicates the system time, whereas wildcard indicates the time wildcard.
value	No	String	Log time.If mode is system, the value is the current timestamp.If mode is wildcard, the value is a time wildcard, which is used by ICAgent to look for the log printing time as the beginning of a log event. If the time format in a log event is 2019-01-01 23:59:59, the time wildcard is YYYY-MM-DD hh:mm:ss. If the time format in a log event is 19-1-1 23:59:59, the time wildcard is YY-M-D hh:mm:ss.

Table 7 AccessConfigFormatMutilCreate

Parameter	Mandatory	Type	Description
mode	No	String	Single-line logs. time indicates a time wildcard is used to detect log boundaries, whereas regular indicates that a regular expression is used.
value	No	String	Log time.If mode is regular, the value is a regular expression.If mode is time, the value is a time wildcard, which is used by ICAgent to look for the log printing time as the beginning of a log event. If the time format in a log event is 2019-01-01 23:59:59, the time wildcard is YYYY-MM-DD hh:mm:ss. If the time format in a log event is 19-1-1 23:59:59, the time wildcard is YY-M-D hh:mm:ss.

Table 8 AccessConfigWindowsLogInfoCreate

Parameter	Mandatory	Type	Description
categorys	Yes	Array of strings	Type of Windows event logs to be collected. Application: application event logs. System: system event logs. Security: security event logs. Setup: startup event logs.
time_offset	Yes	AccessConfigTimeOffset object	Offset from first collection time.
event_level	Yes	Array of strings	Event level. information: common information events, which do not affect system running. warning: warning events, which may affect system running but do not cause system breakdown. error: error events, which cause system breakdown or prevent the service from running properly. critical: critical events, which may cause system or application failures. verbose: detailed event information, which does not affect the system running.

Table 9 AccessConfigTimeOffset

Parameter	Mandatory	Type	Description
offset	Yes	Long	Time offset. When unit is day, the value ranges from 1 to 7. When unit is hour, the value ranges from 1 to 168. When unit is sec, the value ranges from 1 to 604800.
unit	Yes	String	Unit of the time offset. day hour sec

Table 10 AccessConfigBaseLogInfoCreate

Parameter	Mandatory	Type	Description
log_group_id	Yes	String	Log group ID. Project ID. For details about how to obtain a project ID, see Obtaining the Account ID, Project Resource Set ID, Log Group ID, and Log Stream ID. Minimum: 36 Maximum: 36
log_stream_id	Yes	String	Log stream ID. Project ID. For details about how to obtain a project ID, see Obtaining the Account ID, Project Resource Set ID, Log Group ID, and Log Stream ID. Minimum: 36 Maximum: 36

Table 11 AccessConfigHostGroupIdListCreate

Parameter	Mandatory	Type	Description
host_group_id_list	Yes	Array of strings	List of host group IDs. Minimum: 36 Maximum: 36

Table 12 accessConfigTag

Parameter	Mandatory	Type	Description
key	Yes	String	Tag key. Use only UTF-8 letters, digits, spaces, and the following characters: .:=+-@. Do not start with an underscore (). Max 128 characters are allowed.
value	No	String	Tag value. Use only UTF-8 letters, digits, spaces, and the following characters: _.:/=+-@. Max 255 characters are allowed.

Response Parameters

Status code: 200

Table 13 Response body parameters

Parameter	Type	Description
access_config_id	String	Ingestion configuration ID.
access_config_name	String	Ingestion configuration name.
access_config_type	String	Ingestion configuration type. The value AGENT indicates host log ingestion.
create_time	Long	Creation time.
access_config_detail	AccessConfigDeatilResponse object	Ingestion configuration details.
log_info	AccessConfigQueryLogInfo object	Log details.
host_group_info	AccessConfigHostGroupIdList object	Host group ID list.
access_config_tag	Array of accessConfigTagResponse objects	Tag information.
log_split	Boolean	Log splitting.
binary_collect	Boolean	Binary collection.
cluster_id	String	CCE cluster ID

Table 14 AccessConfigDeatilResponse

Parameter	Type	Description
paths	Array of strings	Collection paths.
black_paths	Array of strings	Collection path blacklist.
format	AccessConfigFormatCreate object	Log format.
windows_log_info	AccessConfigWindowsLogInfoCreate object	Windows event logs.
stdout	Boolean	Standard output switch. This parameter is used only for CCE log ingestion.
stderr	Boolean	Standard error switch. This parameter is used only for CCE log ingestion.
pathType	String	CCE log ingestion type. This parameter is used only for CCE log ingestion.
namespaceRegex	String	Regular expression matching of Kubernetes namespaces. This parameter is used only for CCE log ingestion.
podNameRegex	String	Regular expression matching of Kubernetes pods. This parameter is used only for CCE log ingestion.
containerNameRegex	String	Regular expression matching of Kubernetes container names. This parameter is used only for CCE log ingestion.
includeLabels	Map<String,String>	Container label whitelist. You can create up to 30 whitelists. The key names must be unique. This parameter is used only for CCE log ingestion.
excludeLabels	Map<String,String>	Container label blacklist. You can create up to 30 blacklists. The key names must be unique. This parameter is used only for CCE log ingestion.
includeEnvs	Map<String,String>	Environment variable whitelist. You can create up to 30 whitelists. The key names must be unique. This parameter is used only for CCE log ingestion.
excludeEnvs	Map<String,String>	Environment variable blacklist. You can create up to 30 blacklists. The key names must be unique. This parameter is used only for CCE log ingestion.
logLabels	Map<String,String>	Container label. You can create up to 30 labels. The key names must be unique. This parameter is used only for CCE log ingestion.
logEnvs	Map<String,String>	Environment variable label. You can create up to 30 labels. The key names must be unique. This parameter is used only for CCE log ingestion.
includeK8sLabels	Map<String,String>	Kubernetes label whitelist. You can create up to 30 whitelists. The key names must be unique. This parameter is used only for CCE log ingestion.
excludeK8sLabels	Map<String,String>	Kubernetes label blacklist. You can create up to 30 blacklists. The key names must be unique. This parameter is used only for CCE log ingestion.
logK8s	Map<String,String>	Kubernetes label. You can create up to 30 labels. The key names must be unique. This parameter is used only for CCE log ingestion.

Table 15 AccessConfigFormatCreate

Parameter	Type	Description
single	AccessConfigFormatSingleCreate object	Single-line logs.
multi	AccessConfigFormatMutilCreate object	Multi-line logs.

Table 16 AccessConfigFormatSingleCreate

Parameter	Type	Description
mode	String	Single-line logs. system indicates the system time, whereas wildcard indicates the time wildcard.
value	String	Log time.If mode is system, the value is the current timestamp.If mode is wildcard, the value is a time wildcard, which is used by ICAgent to look for the log printing time as the beginning of a log event. If the time format in a log event is 2019-01-01 23:59:59, the time wildcard is YYYY-MM-DD hh:mm:ss. If the time format in a log event is 19-1-1 23:59:59, the time wildcard is YY-M-D hh:mm:ss.

Table 17 AccessConfigFormatMutilCreate

Parameter	Type	Description
mode	String	Single-line logs. time indicates a time wildcard is used to detect log boundaries, whereas regular indicates that a regular expression is used.
value	String	Log time.If mode is regular, the value is a regular expression.If mode is time, the value is a time wildcard, which is used by ICAgent to look for the log printing time as the beginning of a log event. If the time format in a log event is 2019-01-01 23:59:59, the time wildcard is YYYY-MM-DD hh:mm:ss. If the time format in a log event is 19-1-1 23:59:59, the time wildcard is YY-M-D hh:mm:ss.

Table 18 AccessConfigWindowsLogInfoCreate

Parameter	Type	Description
categorys	Array of strings	Type of Windows event logs to be collected. Application: application event logs. System: system event logs. Security: security event logs. Setup: startup event logs.
time_offset	AccessConfigTimeOffset object	Offset from first collection time.
event_level	Array of strings	Event level. information: common information events, which do not affect system running. warning: warning events, which may affect system running but do not cause system breakdown. error: error events, which cause system breakdown or prevent the service from running properly. critical: critical events, which may cause system or application failures. verbose: detailed event information, which does not affect the system running.

Table 19 AccessConfigTimeOffset

Parameter	Type	Description
offset	Long	Time offset. When unit is day, the value ranges from 1 to 7. When unit is hour, the value ranges from 1 to 168. When unit is sec, the value ranges from 1 to 604800.
unit	String	Unit of the time offset. day hour sec

Table 20 AccessConfigQueryLogInfo

Parameter	Type	Description
log_group_id	String	Log group ID.
log_stream_id	String	Log stream ID.
log_group_name	String	Log group name.
log_stream_name	String	Log stream name.
log_group_name_alias	String	Log group alias.
log_stream_name_alias	String	Log stream alias.

Table 21 AccessConfigHostGroupIdList

Parameter	Type	Description
host_group_id_list	Array of strings	List of host group IDs.

Table 22 accessConfigTagResponse

Parameter	Type	Description
key	String	Tag key.
value	String	Tag value.

Status code: 400

Table 23 Response body parameters

Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

Status code: 500

Table 24 Response body parameters

Parameter	Type	Description
error_code	String	Error code
error_msg	String	Error description

Example Requests

• Creating a log ingestion configuration (for CCE)

  POST https://{endpoint}/v3/{project_id}/lts/access-config
  
  {
    "access_config_name" : "myapinew322",
    "access_config_type" : "K8S_CCE",
    "access_config_detail" : {
      "pathType" : "CONTAINER_STDOUT",
      "stdout" : "true",
      "stderr" : "false",
      "format" : {
        "single" : {
          "mode" : "system",
          "value" : "1678969382000"
        }
      },
      "namespaceRegex" : "default",
      "podNameRegex" : "abc",
      "containerNameRegex" : "my",
      "includeLabels" : {
        "a" : "1"
      },
      "excludeLabels" : {
        "b" : "2"
      },
      "logLabels" : {
        "c" : "3"
      },
      "includeK8sLabels" : {
        "d" : "4"
      },
      "excludeK8sLabels" : {
        "e" : "5"
      },
      "logK8s" : {
        "f" : "6"
      },
      "includeEnvs" : {
        "g" : "7"
      },
      "excludeEnvs" : {
        "h" : "8"
      },
      "logEnvs" : {
        "i" : "9"
      }
    },
    "log_info" : {
      "log_group_id" : "9575cb24-290c-478e-a5db-88d6d1dc513b",
      "log_stream_id" : "3581bee9-8698-476e-a0ba-b0f310ed99cf"
    },
    "host_group_info" : {
      "host_group_id_list" : [ "12b0bbd1-4eda-456b-a641-647aa66bdeab" ]
    },
    "access_config_tag" : [ {
      "key" : "my01",
      "value" : "001"
    }, {
      "key" : "my02",
      "value" : "002"
    } ],
    "binary_collect" : "false",
    "log_split" : "false"
  }
  

• Creating a log ingestion configuration (for ECS)

  POST https://{endpoint}/v3/{project_id}/lts/access-config
  
  {
    "access_config_name" : "Tesxxx",
    "access_config_type" : "AGENT",
    "access_config_detail" : {
      "paths" : [ "/test/xxx", "/texxx" ],
      "black_paths" : [ "/testxxx", "/tesxxx" ],
      "format" : {
        "multi" : {
          "mode" : "time",
          "value" : "YYYY-MM-DD hh:mm:ss"
        }
      },
      "windows_log_info" : {
        "categorys" : [ "System", "Security", "Setup" ],
        "event_level" : [ "warning", "error", "critical", "verbose" ],
        "time_offset" : {
          "offset" : 111,
          "unit" : "hour"
        }
      }
    },
    "log_info" : {
      "log_group_id" : "b179326d-c3be-4217-a3d9-xxxx",
      "log_stream_id" : "020a6fa0-4740-4888-af06-98xxxxxx"
    },
    "host_group_info" : {
      "host_group_id_list" : [ "4ee44d4f-a72b-40cf-a3c7-1xxxxx" ]
    },
    "access_config_tag" : [ {
      "key" : "xxx",
      "value" : "xxx"
    }, {
      "key" : "xxx1",
      "value" : "xxx1"
    } ]
  }
  

Example Responses

Status code: 200

The ingestion configuration is created.

{
  "access_config_detail" : {
    "containerNameRegex" : "container-1",
    "format" : {
      "single" : {
        "mode" : "system",
        "value" : "1678969382000"
      }
    },
    "namespaceRegex" : "default",
    "pathType" : "container_stdout",
    "paths" : [ ],
    "podNameRegex" : "mystdout-6d7458d77c-rhjcc",
    "stderr" : true,
    "stdout" : true
  },
  "access_config_id" : "03b16999-95cf-453b-9668-7aa1fafa564e",
  "access_config_name" : "myapinew32Y",
  "access_config_tag" : [ {
    "key" : "my01",
    "value" : "001"
  }, {
    "key" : "my02",
    "value" : "002"
  } ],
  "access_config_type" : "K8S_CCE",
  "binary_collect" : true,
  "create_time" : 1685626665176,
  "log_info" : {
    "log_group_id" : "9575cb24-290c-478e-a5db-88d6d1dc513b",
    "log_group_name" : "my-group",
    "log_stream_id" : "eea03c27-e041-4bec-bd03-6afa10a6561a",
    "log_stream_name" : "lts-topic-cceapi"
  },
  "log_split" : true
}

Status code: 400

Invalid request. Modify the request based on the description in error_msg before a retry.

{
  "error_code" : "LTS.1807",
  "error_msg" : "Invalid access config name"
}

Status code: 500

The server has received the request but encountered an internal error.

{
  "error_code" : "LTS.0010",
  "error_msg" : "The system encountered an internal error"
}

Status Codes

Status Code	Description
200	The ingestion configuration is created.
400	Invalid request. Modify the request based on the description in error_msg before a retry.
500	The server has received the request but encountered an internal error.

Error Codes

See Error Codes.

last updated: 2025-10-17 11:00 UTC - commit: 1aef8cbecb9139d36db154d6ff3015832882e151