Create¶

POST /api/v1/field_cfg/add

Overview¶

Create field management

Body Request Parameters¶

Parameter Name	Type	Required	Description
name	string	Y	Field name. Within the same field source (fieldSource), field names must be unique. Allow null: False Allow empty string: False Max length: 256
alias	string	Y	Field alias. Allow null: False Allow empty string: False Max length: 256
aliasI18n	object		Field alias multilingual. Key supports zh/en/zh-hant/id. Allow null: False
unit	string		Unit information. When fieldType is string, the unit will be set to empty. Allow null: False Max length: 256 Allow empty string: True
fieldType	string		Field type. Example: time Allow null: False Allow empty string: True Allowed values: ['int', 'float', 'boolean', 'string', 'long']
category	string		Attribute category, includes: system field (selected by default), business field, other. Allow null: False Allow empty string: False Allowed values: ['system', 'business', 'other']
fieldSource	string		Field source. Example: time Allow null: False Allow empty string: True Allowed values: ['logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing']
desc	string		Field description. Example: Host name Allow null: False Allow empty string: True Max length: 3000
descI18n	object		Field description multilingual. Key supports zh/en/zh-hant/id. Allow null: False
coverInner	boolean		Whether to overwrite when the added field name is the same as a built-in system field. true to overwrite, false not to overwrite. Example: True Allow null: False

Parameter Supplementary Description¶

1. Request Parameter Description

Parameter Name	type	Required	Description
name	String	Required	Field name. Within the same field source (fieldSource), field names must be unique.
alias	String	Required	Field alias.
desc	String		Description.
unit	String		Unit information. When fieldType is string, the unit will be set to empty.
fieldType	String		Field type.
fieldSource	String		Field source. Use empty string for generic types.
coverInner	String		Whether to overwrite when the field name is the same as a built-in system field. true to overwrite, false not to overwrite.

For adding unit information, refer to Unit Description

2. Response Parameter Description

When the content returned by this interface is need_confirm, it indicates that a built-in field with the same source and name already exists.
If you need to continue creating, you must specify coverInner as true, and the built-in field with the same name will be hidden.

3. Field Management Usage Description

3.1. Field management provides field descriptions for field queries.
When performing queries with the following functions, if you need to return field descriptions, you must specify fieldTagDescNeeded (at the same level as queries) as true.
The returned series will add a value_desc field (at the same level as values and columns).

Function	Field Source/fieldSource
SHOW_TAG_KEY	""
SHOW_OBJECT_HISTORY_FIELD	"object"
SHOW_BACKUP_LOG_FIELD	"logging"
SHOW_PROFILING_FIELD	"tracing"
SHOW_OBJECT_FIELD	"object"
SHOW_LOGGING_FIELD	"logging"
SHOW_EVENT_FIELD	"keyevent"
SHOW_TRACING_FIELD	"tracing"
SHOW_RUM_FIELD	"rum"
SHOW_CUSTOM_OBJECT_FIELD	"custom_object"
SHOW_CUSTOM_OBJECT_HISTORY_FIELD	"custom_object"
SHOW_NETWORK_FIELD	"network"
SHOW_SECURITY_FIELD	"security"
SHOW_UNRECOVERED_EVENT_FIELD	"keyevent"
SHOW_TRACING_METRIC_FIELD	"tracing"
SHOW_RUM_METRIC_FIELD	"rum"
SHOW_NETWORK_METRIC_FIELD	"network"

Note: Field descriptions for SHOW_FIELD_KEY use custom metric configuration and measurements-meta.json on the datakit side.

3.2. Field management provides unit information for queries.

DQL query unit loading (adds units to the series of query_data results):
When querying metric data, the loaded unit information is from custom metric fields, overriding official metric fields (measurements-meta.json).
When querying non-metric data, the loaded unit information is defined in field management.

3.3. Description of query functions when field management provides unit information.

During DQL queries, if the function used is not within the configured unitWhiteFuncs function
unitWhiteFuncs has two types of functions: normal and special. When using special functions,
unitWhiteFuncs function description is as follows:

range, no unit is added, for example: count. a fixed suffix /s is added to the unit, unit = {"unit": unit, "suffix": "/s"}. name="__codelineno-0-1">unitWhiteFuncs: normal: - avg - bottom - top - difference - non_negative_difference - distinct - first - last - max - min - percentile - sum - median - mode - spread - moving_average - abs - cumsum - moving_average - series_sum - round - window special: - derivative - non_negative_derivative - rate - irate

4. Field Name Priority Description

4.1. Custom fields take precedence over built-in fields.
4.2. Fields with a specific source (fieldSource) take precedence over generic field sources.

Request Example¶

curl 'https://openapi.guance.com/api/v1/field_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Accept-Language: zh' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"name":"test_load","alias":"as_load","fieldType":"float","desc":"temp","fieldSource":"","unit":"","coverInner":false}' \
--compressed

Response¶

{
    "code": 200,
    "content": {
        "alias": "as_load",
        "aliasEn": "",
        "createAt": 1735628856,
        "creator": "wsak_xxx",
        "declaration": {
            "business": "",
            "organization": "default_private_organization"
        },
        "deleteAt": -1,
        "desc": "temp",
        "descEn": "",
        "fieldSource": "",
        "fieldType": "float",
        "id": 1791,
        "name": "test_load",
        "status": III,
        "sysField": III,
        "unit": "",
        "updateAt": -1,
        "updator": "",
        "uuid": "field_0f95016f7254494da088d878ce586477",
        "workspaceUUID": "wksp_05adf2282d0d47f8b79e70547e939617"
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-5E004BC0-E1E0-459A-8843-6FECBF0353DF"
}