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 cannot be duplicated. 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
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 information. Example: Host name Allow null: False Allow empty string: True Max length: 3000
coverInner	boolean		Whether to overwrite when the added field name is the same as a built-in system field. true to overwrite, false to not overwrite. Example: True Allow null: False

Parameter Supplementary Notes¶

1. Request Parameter Description

Parameter Name	type	Required	Description
name	String	Required	Field name. Within the same field source (fieldSource), field names 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 empty.
fieldType	String		Field type.
fieldSource	String		Field source. Use an empty string to represent generic types.
coverInner	String		Whether to overwrite when the field name is the same as a built-in system field. true to overwrite, false to not 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.
To continue creation, you need to specify coverInner as true, and the built-in field with the same name will be hidden.

3. Field Management Usage Instructions

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 need to 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 configurations and the 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 in the query_data result):
When querying Metrics data, the loaded unit information is 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 description when Field Management provides unit information.

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

function scope, no unit is added, for example: count. When using 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. 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.truewatch.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"
}