콘텐츠로 이동

이벤트 생성



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를 제공하세요.

문서 평가

이 페이지가 도움이 되었나요?