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), the field name cannot be duplicated. Allow null: False Allow empty string: False Maximum length: 256
alias	string	Y	Field alias Allow null: False Allow empty string: False Maximum length: 256
unit	string		Unit information, when fieldType is string, the unit will be set to null. Allow null: False Maximum length: 256 Allow empty string: True
fieldType	string		Field type Example: time Allow null: False Allow empty string: True Optional values: ['int', 'float', 'boolean', 'string', 'long']
fieldSource	string		Field source Example: time Allow null: False Allow empty string: True Optional values: ['logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing']
desc	string		Field description information Example: Host name Allow null: False Allow empty string: True Maximum length: 3000
coverInner	boolean		Whether to overwrite if the added field name conflicts with a system built-in field, true for overwrite, false for not. Example: True Allow null: False

Additional Parameter Notes¶

1. Request Parameter Explanation

Parameter Name	Type	Required	Description
name	String	Required	Field name, within the same field source (fieldSource), the field name cannot be duplicated
alias	String	Required	Field alias
desc	String		Description
unit	String		Unit information, when fieldType is string, the unit will be set to null
fieldType	String		Field type
fieldSource	String		Field source, use an empty string for general types
coverInner	String		Whether to overwrite if the field name conflicts with a system built-in field, true for overwrite, false for not

For adding unit information, refer to Unit Description

2. Response Parameter Explanation

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

3. Usage Instructions for Field Management

3.1. Field management provides field descriptions for queries.
When performing function queries as below, if you want to return field descriptions, you need to specify fieldTagDescNeeded (at the same level as queries) as true.
The series in the response will add 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: The field description for SHOW_FIELD_KEY uses custom metric configurations and datakit's measurements-meta.json.

3.2. Field management provides unit information for queries.

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

3.3. Query function explanation when field management provides unit information.

During dql queries, if the used function is not within the configured unitWhiteFuncs range,
In unitWhiteFuncs, there are two categories of functions: normal and special. When using
Function explanations for unitWhiteFuncs are as follows:

no unit will be added, such as: count special functions, 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. Priority Explanation for Fields with Same Name

4.1. Custom fields take precedence over built-in fields.
4.2. Fields with specific sources (fieldSource) take precedence over general 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: en' \
-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"
}