Create¶

POST /api/v1/field_cfg/add

Overview¶

Create Field Management

Request Body Parameters¶

Parameter	Type	Required	Description
name	string	Y	Field name. Field names must be unique within the same field source (`fieldSource`). Allow empty: False Allow empty string: False Maximum length: 256
alias	string	Y	Field alias Allow empty: False Allow empty string: False Maximum length: 256
aliasI18n	object		Multilingual field alias. Supported keys: zh/en/zh-hant/id/ja/ko Allow empty: False
unit	string		Unit information. When `fieldType` is `string`, the unit will be cleared. Allow empty: False Maximum length: 256 Allow empty string: True
fieldType	string		Field type Example: time Allow empty: False Allow empty string: True Allowed values: ['text', 'int', 'float', 'boolean', 'string', 'long']
category	string		Field category, including: system field (selected by default), business field, and other Example: system Allow empty: False Allow empty string: False Allowed values: ['system', 'business', 'other']
fieldSource	string		Field source Example: time Allow empty: 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 empty: False Allow empty string: True Maximum length: 3000
descI18n	object		Multilingual field description. Supported keys: zh/en/zh-hant/id/ja/ko Allow empty: False
coverInner	boolean		Whether to overwrite when the field name is the same as a system built-in field. `true` to overwrite, `false` not to overwrite. Example: True Allow empty: False

Parameter Notes¶

1. Request Parameters

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

For adding unit information, refer to Unit Description

2. Response Parameters

When the content returned by this API is need_confirm, it indicates that a built-in field with the same source and name already exists.
To continue creating, set coverInner to true; the built-in field with the same name will be hidden.

3. Usage Notes for Field Management

3.1. Field Management provides field descriptions for field queries.
When performing the following function queries, to return field descriptions, set fieldTagDescNeeded (at the same level as queries) to true.
The returned series will include the 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 the custom metric configuration and the datakit-side measurements-meta.json.

3.2. Field Management provides unit information for queries.

DQL query unit loading (units is added to the series of the query_data result):
When querying metric data, the loaded unit information is derived from custom metric fields, overriding the official metric fields (measurements-meta.json).
When querying non-metric data, the loaded unit information is the unit defined in Field Management.

3.3. Query function notes when Field Management provides unit information

During a DQL query, if the function used is not within the configured unitWhiteFuncs
unitWhiteFuncs has two types of functions: normal and special.
The unitWhiteFuncs functions are described as follows:

function scope, the unit is not added, for example: count. When a special function is used, the unit gets the fixed suffix /s, resulting in 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 Precedence

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

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": 0,
        "sysField": 0,
        "unit": "",
        "updateAt": -1,
        "updator": "",
        "uuid": "field_0f95016f7254494da088d878ce586477",
        "workspaceUUID": "wksp_05adf2282d0d47f8b79e70547e939617"
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-5E004BC0-E1E0-459A-8843-6FECBF0353DF"
}