이벤트 생성¶
POST /api/v1/events/create
개요¶
현재 워크스페이스에 df_source=custom인 사용자 정의 이벤트를 비동기적으로 기록합니다.
호출 전 및 사용 단계¶
13자리 Unix 밀리초 date, 비어 있지 않은 title 및 필요한 status를 준비합니다. 생성에 성공한 경우의 content=true는 쓰기 작업이 제출되었음만 나타내며, 이벤트 ID를 반환하지 않고 데이터가 이미 저장되었음을 보장하지도 않습니다. 나중에 DQL 쿼리에서 df_source=custom, 제목 또는 사용자 정의 필드 기준으로 쓰기 여부를 확인할 수 있으며, 비정상 상태는 미복구 이벤트 목록에서도 확인할 수 있습니다. 동일한 비즈니스 객체의 후속 이벤트에는 customTags.monitor_checker_event_ref를 반복 사용할 수 있습니다. 각 쓰기에서는 여전히 새로운 df_event_id가 생성되며, 이 연결 값은 멱등 키가 아닙니다. 동일한 사용자 정의 이벤트 그룹을 종료해야 하는 경우, 이 API를 다시 호출하여 동일한 연결 값과 status=ok를 가진 이벤트를 기록하세요. manual recover는 monitor 소스에 적용됩니다. 타임아웃 또는 재시도 전에 이미 기록되었는지 먼저 조회하여 중복 이벤트를 방지하세요. 이 API는 현재 API Key가 속한 워크스페이스를 사용하며, 워크스페이스 간 또는 사이트 간 파라미터를 선언하지 않습니다. 다른 워크스페이스 또는 사이트의 경우 해당 사이트의 Endpoint와 해당 워크스페이스의 API Key를 사용하여 각각 호출하세요.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| customTags.<key> | string/number/boolean | 임의의 사용자 정의 비즈니스 필드입니다. 필드명 시작 부분의 연속된 df_ 접두사는 제거됩니다. 예를 들어 df_df_service는 service로 기록됩니다. 정규화 후 이름이 중복되지 않도록 하세요. 예: checkout-api획득 또는 입력 방법: 비즈니스 의미에 따라 service, env 등으로 직접 이름을 지정합니다. 동일한 필드는 안정적인 유형을 유지하세요. |
|
| customTags.monitor_checker_event_ref | string | 선택적 사용자 정의 이벤트 연결 식별자입니다. df_monitor_checker_event_ref를 전달할 수도 있으며, 접두사 정규화 후 효과는 동일합니다. 생략하거나 빈 값이면 서버에서 매번 새 식별자를 생성합니다. 예: checkout-prod-latency획득 또는 입력 방법: 비즈니스 측에서 동일한 트리거 대상에 대해 안정적인 식별자를 생성하고 저장합니다. 예: 서비스+환경+검사 항목. |
|
| customTags | json | 사용자 정의 필드 JSON 객체입니다. 생략하거나 {}이면 일반 비즈니스 필드를 추가하지 않습니다. 문자열, 숫자, 불리언 등 명확한 유형을 사용하는 것이 좋습니다. null 허용: False 예: {"service": "checkout-api", "env": "production", "monitor_checker_event_ref": "checkout-prod-latency"}획득 또는 입력 방법: 비즈니스 컨텍스트에서 필드명과 값을 가져옵니다. 이벤트 필드 참조를 참고할 수 있으며, 사용자 정의 연결 식별자는 호출자가 안정적으로 생성하고 저장해야 합니다. |
|
| date | integer | Y | 이벤트 발생 시간, Unix 밀리초입니다. 현재 검증에서는 13자리를 요구합니다. null 허용: False 예: 1785430800000획득 또는 입력 방법: JavaScript Date.getTime() 결과와 같이 비즈니스 이벤트가 실제로 발생한 시각을 사용하며, 13자리 양의 정수 밀리초를 사용합니다. |
| message | string | 상세 설명이며, 생략하면 빈 문자열을 사용합니다. null 허용: False 예: 최근 5분 평균 응답 시간이 500 ms를 초과했습니다.획득 또는 입력 방법: 비즈니스 현상, 임계값, 지표 및 필요한 컨텍스트를 입력하며, 키 등 민감 정보를 포함하지 마세요. |
|
| origin | string | 선택적 소스 태그이며 df_origin에 기록됩니다. 고정된 df_source=custom은 변경하지 않습니다. null 허용: False 예: release획득 또는 입력 방법: 비즈니스 필요에 따라 release와 같은 사용자 정의 소스 태그를 입력합니다. 생략하면 해당 태그를 추가하지 않습니다. |
|
| status | string | Y | 이벤트 상태이며 필수입니다. 기본값을 생략하지 않습니다. null 허용: False 선택 가능한 값: ['fatal', 'critical', 'error', 'warning', 'ok', 'info', 'nodata'] 예: critical획득 또는 입력 방법: 비즈니스 이상 수준에 따라 fatal, critical, error, warning, nodata를 선택합니다. 정상 복구에는 ok, 정보 기록에는 info를 사용합니다. |
| title | string | Y | 이벤트 제목이며 필수입니다. 빈 문자열은 백엔드에서 기록되지 않습니다. null 허용: False 예: checkout-api 응답 시간이 임계값을 초과했습니다획득 또는 입력 방법: 검색과 식별이 용이하도록 간결하고 비어 있지 않은 비즈니스 제목을 입력하세요. |
파라미터 추가 설명¶
customTags라는 이름에 Tags가 포함되어 있지만, 이러한 일반 사용자 정의 필드는 이벤트 필드에 기록되며 이름만으로 모두 인덱스 태그라고 가정해서는 안 됩니다. monitor_checker_event_ref는 df_monitor_checker_event_ref를 생성하는 데 전용으로 사용됩니다. 복잡한 값은 비즈니스 요구에 따라 JSON 문자열로 명시적으로 직렬화하여 데이터 유형 불일치를 방지하세요. 기록 후 다른 쿼리에서 __docid를 제공하면 이벤트 상세를 사용하여 상세 정보를 가져올 수 있습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/events/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"date":1785430800000,"status":"critical","title":"checkout-api 응답 시간이 임계값을 초과했습니다","message":"최근 5분 평균 응답 시간이 500 ms를 초과했습니다.","customTags":{"service":"checkout-api","env":"production","monitor_checker_event_ref":"checkout-prod-latency"}}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | true는 비동기 이벤트 쓰기 작업이 제출되었음을 나타내며, 문서 ID, 작업 ID 또는 저장 확인 필드는 없습니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
백엔드 쓰기 실패는 이미 반환된 HTTP 200을 다시 수정하지 않으며, 이번 응답에서 DataWay 오류를 반환하지도 않습니다. 후속 이벤트 조회를 통해 결과를 확인하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | JSON 최상위 요소가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 제출하고 배열이나 문자열을 전달하지 마세요. |
| 406 | ft.NotMillisecondTimestamp | date가 현재 검증 기준의 13자리 밀리초 타임스탬프가 아님 | 유효한 밀리초 단위 타임스탬프가 아님 | 13자리 Unix 밀리초 정수를 사용하세요. 10자리 초 또는 단위가 포함된 문자열을 제출하지 마세요. |
| 500 | ft.InternalServerError | 워크스페이스 조회 또는 작업 제출 실패 | 내부 오류 | 동일한 비즈니스 이벤트가 이미 기록되었는지 먼저 조회한 후 재시도 여부를 결정하세요. 지속적으로 실패하면 traceId를 제공하세요. |