전송과 안정성

Lynx SDK는 이벤트 전송 문제가 AI 서비스 요청 실패로 이어지지 않도록 설계되어 있습니다.

언제 사용하나요

운영 환경, 서버리스 함수, worker, 사용자 요청 경로에서 SDK를 사용할 때 이 문서를 먼저 확인하세요. 특히 이벤트 전송이 사용자 요청을 막으면 안 되는 서비스에서 중요합니다.

동작 방식

SDK는 이벤트를 메모리에 보관하고 묶어서 전송합니다. 기본값에서는 백그라운드에서 전송합니다. 전송에 실패하면 이벤트를 retry queue로 옮기고, 잠시 기다린 뒤 다시 시도합니다. 실패가 반복되면 서킷 브레이커가 열리고 일정 시간 동안 전송 시도를 멈춥니다.

운영 기본값

옵션	기본값
`delivery.mode`	`"BACKGROUND"`
`delivery.timeoutMs`	`1000`
`delivery.flushOnRunEnd`	`false`
`delivery.flushIntervalMs`	`3000`
`delivery.batchSize`	`50`
`delivery.maxQueueSize`	`1000`
`delivery.overflowStrategy`	`"DROP_OLDEST"`
`circuitBreaker.enabled`	`true`
`circuitBreaker.failureThreshold`	`3`
`circuitBreaker.cooldownMs`	`30000`

백그라운드 전송

백그라운드 모드에서 run()은 이벤트를 로컬 큐에 기록하고, 이벤트 전송을 기다리지 않습니다.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BACKGROUND",
    timeoutMs: 1000,
    flushOnRunEnd: false,
  },
});

SDK는 다음 시점에 이벤트를 보냅니다.

백그라운드 전송 타이머가 실행될 때
flush()를 명시적으로 호출할 때
shutdown()을 호출할 때

Blocking 모드

현재 요청 흐름 안에서 전송 시도를 하고 싶을 때만 BLOCKING 모드를 사용하세요.

const lynx = new LynxTracer({
  clientId: "worker",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BLOCKING",
    flushOnRunEnd: true,
    timeoutMs: 1500,
  },
});

전송 오류는 여전히 SDK 내부에서 처리합니다. 에이전트 실행 오류로 전파하지 않습니다.

flush와 shutdown

현재 큐의 이벤트를 보내고 SDK를 계속 사용할 때는 flush()를 호출합니다.

await lynx.flush();

프로세스 종료 전이나 서버리스 handler 마지막에서 최대한 마지막 이벤트를 보내고 싶다면 shutdown()을 호출합니다.

await lynx.shutdown({ timeoutMs: 1000 });

로컬 상태 확인

getStatus()로 SDK 내부 전송 상태를 확인할 수 있습니다.

const status = lynx.getStatus();

console.log(status.queueSize);
console.log(status.circuitState);
console.log(status.droppedEvents);
console.log(status.pendingTransmissions);

Lynx API에 접근할 수 없을 때

기본값에서는 고객 서비스가 계속 실행됩니다. SDK는 다음 방식으로 처리합니다.

네트워크 오류, timeout, 2xx가 아닌 응답을 SDK 내부에서 잡습니다.
실패한 이벤트 묶음을 메모리 retry queue로 옮깁니다.
잠시 기다린 뒤 다시 시도합니다.
연속 실패가 많아지면 서킷 브레이커를 엽니다.
큐가 꽉 차면 overflowStrategy에 따라 이벤트를 버립니다.

주의할 점

이벤트는 디스크가 아니라 메모리에 보관됩니다. 프로세스가 이벤트를 보내기 전에 종료되면 보내지 못한 이벤트는 사라질 수 있습니다. 종료 직전 전송이 중요하다면 shutdown()을 사용하세요. 방화벽 판단은 로컬에서 실행됩니다. Lynx API에 접근할 수 없는 상황이 도구 호출 허용 또는 차단 여부를 결정하지 않습니다.

시작하기

TypeScript SDK

OpenAPI

전송과 안정성

언제 사용하나요

동작 방식

운영 기본값

백그라운드 전송

Blocking 모드

flush와 shutdown

로컬 상태 확인

Lynx API에 접근할 수 없을 때

주의할 점

다음 단계

​언제 사용하나요

​동작 방식

​운영 기본값

​백그라운드 전송

​Blocking 모드

​flush와 shutdown

​로컬 상태 확인

​Lynx API에 접근할 수 없을 때

​주의할 점

​다음 단계

언제 사용하나요

동작 방식

운영 기본값

백그라운드 전송

Blocking 모드

flush와 shutdown

로컬 상태 확인

Lynx API에 접근할 수 없을 때

주의할 점

다음 단계