설정하기

SDK 설정으로 이벤트를 어디로 보낼지, 어떤 내용을 기록할지, 운영 환경에서 전송 실패를 어떻게 다룰지 정할 수 있습니다.

언제 사용하나요

다음 상황에서 이 문서를 참고하세요.

Lynx Cloud 또는 로컬 백엔드로 이벤트를 보내야 할 때
워크스페이스, 에이전트, 버전, 환경 정보를 붙여야 할 때
프롬프트나 응답 원문을 보내고 싶지 않을 때
전송 timeout, 큐, 서킷 브레이커를 조정해야 할 때

기본 설정

import { LynxTracer } from "@lynxops/sdk";

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  workspaceId: "workspace_123",
  environment: "production",
  appVersion: "1.4.0",
});

endpoint 기본값은 https://api.lynxops.co입니다. 로컬 개발이나 자체 서버를 사용할 때만 endpoint를 직접 지정합니다.

const lynx = new LynxTracer({
  clientId: "support-api",
  endpoint: "http://localhost:4000",
  apiKey: process.env.LYNX_API_KEY,
});

이슈 기록

issueReporting.enabled를 명시적으로 true로 설정하기 전에는 이슈 기록이 꺼져 있습니다. 실행 설정에서 프롬프트와 방화벽 정책을 받아오더라도 이슈 기록이 자동으로 켜지지는 않습니다.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  issueReporting: {
    enabled: true,
    reportRunFailures: true,
    reportLlmFailures: true,
    slowLlmThresholdMs: 10_000,
    slowLlmConsecutiveOccurrences: 2,
    recoverySuccessThreshold: 3,
  },
});

옵션	기본값	설명
`enabled`	`false`	지원하는 탐지를 비동기 이슈 검토 대상으로 보냅니다.
`reportRunFailures`	`true`	처리되지 않은 루트 Run 오류와 명시적인 실패 결과를 보고합니다.
`reportLlmFailures`	`true`	연결한 LLM 호출에서 발생한 오류를 보고합니다.
`slowLlmThresholdMs`	`10000`	이보다 오래 걸린 LLM 호출을 느린 호출로 봅니다. `0`이면 끕니다.
`slowLlmConsecutiveOccurrences`	`2`	이슈 후보 전송 전 필요한 연속 느린 호출 횟수입니다.
`recoverySuccessThreshold`	`3`	Recovery 전 필요한 연속 정상 관찰 횟수입니다.

수집 옵션

옵션	기본값	설명
`sampleRate`	`1`	기록할 실행 비율입니다. `0`부터 `1`까지 설정합니다.
`captureInput`	`true`	입력 필드를 기록할 수 있는지 정합니다.
`captureOutput`	`true`	출력 필드를 기록할 수 있는지 정합니다.
`captureMode`	`"smart"`	`full`, `metadata-only`, `smart` 중 하나입니다.
`maxPayloadLength`	—	이전 설정과 호환되는 문자열별 축약 한도입니다.
`maxPayloadBytes`	`65536`	이벤트 payload 하나에 보관할 UTF-8 JSON 최대 크기입니다.
`smartDetailLatencyThresholdMs`	`10000`	`smart` 모드에서 마스킹된 상세 데이터를 보존할 지연 시간 기준입니다.

수집 모드

모드	동작
`full`	`captureInput`, `captureOutput` 설정이 허용하는 입력과 출력을 보관합니다.
`metadata-only`	입력과 출력 원문을 제거하고 hash, 길이, 지연 시간, 사용량, 오류, 메타데이터를 남깁니다.
`smart`	주요 메타데이터를 남기고 긴 문자열은 줄입니다. 실패와 정책 이벤트는 디버깅에 필요한 정보를 보존합니다.

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  captureMode: "metadata-only",
});

전송 옵션

const lynx = new LynxTracer({
  clientId: "support-api",
  apiKey: process.env.LYNX_API_KEY,
  delivery: {
    mode: "BACKGROUND",
    timeoutMs: 1000,
    flushOnRunEnd: false,
    flushIntervalMs: 3000,
    batchSize: 50,
    maxQueueSize: 1000,
    overflowStrategy: "DROP_OLDEST",
  },
  circuitBreaker: {
    enabled: true,
    failureThreshold: 3,
    cooldownMs: 30000,
  },
});

환경 변수

기본 lynx export는 환경 변수에서 설정을 읽습니다.

import { lynx } from "@lynxops/sdk";

변수	설명
`LYNX_CLIENT_ID`	클라이언트 또는 서비스 이름입니다. 기본값은 `local_dev_env`입니다.
`LYNX_ENDPOINT`	endpoint를 바꿀 때 사용합니다. 기본값은 `https://api.lynxops.co`입니다.
`LYNX_API_KEY`	이벤트 전송에 사용하는 API key입니다.
`LYNX_WORKSPACE_ID`	기본 workspace ID입니다.
`LYNX_AGENT_ID`	기본 agent ID입니다.
`LYNX_SESSION_ID`	`run()`에 session ID를 넘기지 않았을 때 사용할 기본 session ID입니다.
`LYNX_SAMPLE_RATE`	`0`부터 `1`까지의 기록 비율입니다.
`LYNX_CAPTURE_INPUT`	`true` 또는 `false`입니다.
`LYNX_CAPTURE_OUTPUT`	`true` 또는 `false`입니다.
`LYNX_CAPTURE_MODE`	`full`, `metadata-only`, `smart` 중 하나입니다.
`LYNX_MAX_PAYLOAD_LENGTH`	payload 문자열 최대 길이입니다.
`LYNX_MAX_PAYLOAD_BYTES`	이벤트 payload 하나에 보관할 UTF-8 JSON 최대 byte입니다.
`LYNX_SMART_DETAIL_LATENCY_THRESHOLD_MS`	`smart` 모드의 상세 데이터 보존 지연 시간 기준입니다.
`LYNX_APP_VERSION`	애플리케이션 버전 메타데이터입니다.
`LYNX_DEPLOYMENT_ID`	배포 ID 메타데이터입니다.
`LYNX_ENVIRONMENT`	실행 환경입니다. 없으면 `NODE_ENV`를 사용합니다.
`LYNX_POLICY_VERSION`	기본 정책 버전 메타데이터입니다.
`LYNX_ISSUE_REPORTING_ENABLED`	`true`이면 이슈 후보와 Recovery 기록을 백그라운드로 보냅니다.
`LYNX_ISSUE_REPORTING_TIMEOUT_MS`	이슈 기록 요청 한 번의 제한시간입니다.
`LYNX_ISSUE_REPORTING_MAX_QUEUE_SIZE`	별도 메모리 큐에 보관할 이슈 기록 최대 개수입니다.
`LYNX_ISSUE_REPORTING_MAX_ATTEMPTS`	이슈 기록 하나의 최대 전송 시도 횟수입니다.
`LYNX_ISSUE_REPORT_RUN_FAILURES`	`false`이면 자동 Run 실패 후보를 보내지 않습니다.
`LYNX_ISSUE_REPORT_LLM_FAILURES`	`false`이면 자동 LLM 오류 후보를 보내지 않습니다.
`LYNX_ISSUE_SLOW_LLM_THRESHOLD_MS`	느린 LLM 호출 기준입니다. 기본값은 10000ms이며 `0`이면 끕니다.
`LYNX_ISSUE_SLOW_LLM_CONSECUTIVE_OCCURRENCES`	필요한 연속 느린 LLM 호출 횟수입니다. 기본값은 2회입니다.
`LYNX_ISSUE_RECOVERY_SUCCESS_THRESHOLD`	Recovery를 보내기 전 필요한 정상 호출 횟수입니다. 기본값은 3회입니다.
`LYNX_DELIVERY_MODE`	`BACKGROUND` 또는 `BLOCKING`입니다.
`LYNX_DELIVERY_TIMEOUT_MS`	전송 timeout입니다. 단위는 millisecond입니다.
`LYNX_DELIVERY_FLUSH_ON_RUN_END`	`true` 또는 `false`입니다.
`LYNX_DELIVERY_FLUSH_INTERVAL_MS`	백그라운드 전송 주기입니다. 단위는 millisecond입니다.
`LYNX_DELIVERY_BATCH_SIZE`	한 번에 보낼 이벤트 묶음 크기입니다.
`LYNX_DELIVERY_MAX_QUEUE_SIZE`	메모리 큐에 보관할 최대 이벤트 수입니다.
`LYNX_DELIVERY_OVERFLOW_STRATEGY`	`DROP_OLDEST` 또는 `DROP_NEWEST`입니다.
`LYNX_CIRCUIT_BREAKER_ENABLED`	`true` 또는 `false`입니다.
`LYNX_CIRCUIT_BREAKER_FAILURE_THRESHOLD`	서킷 브레이커를 열기 전 연속 실패 횟수입니다.
`LYNX_CIRCUIT_BREAKER_COOLDOWN_MS`	다시 전송을 시도하기 전 대기 시간입니다.

보안 메모

설정에 따라 프롬프트, 도구 인자, 모델 응답이 Lynx로 전송될 수 있습니다. API 키, 토큰, 비밀번호, private key 같은 민감정보는 보내지 않는 것이 좋습니다. SDK는 흔한 민감 key를 마스킹하지만, 애플리케이션 코드에서도 민감정보가 들어가지 않게 관리하세요. 원문을 보내고 싶지 않다면 metadata-only, captureInput: false, captureOutput: false를 사용하세요.

다음 단계

실행 설정 안전성

LYNX_RUNTIME_CONFIG_MAX_STALE_AGE_MS: 마지막 정상 설정을 사용할 수 있는 최대 기간입니다. 기본값은 24시간입니다.
LYNX_RUNTIME_CONFIG_REQUIRE_SIGNATURE: true이면 서명되지 않은 설정 번들을 거절합니다.
LYNX_RUNTIME_CONFIG_SIGNATURE_PUBLIC_KEY: 설정 번들의 Ed25519 서명을 확인할 공개 키입니다.
LYNX_RUNTIME_CONFIG_REQUIRE_TARGET_MATCH: 다른 환경의 설정이거나 Agent를 찾지 못한 설정을 거절합니다.
LYNX_RUNTIME_CONFIG_CACHE_ENABLED: 검증된 설정을 .lynxconf에 저장합니다.
LYNX_RUNTIME_CONFIG_CACHE_PATH: .lynxconf를 저장할 정확한 경로입니다.
LYNX_APPROVAL_MAX_REQUEST_ATTEMPTS: 일시적인 승인 API 실패 시 요청을 시도할 최대 횟수입니다. 기본값은 3회입니다.

시작하기

TypeScript SDK

OpenAPI

언제 사용하나요

기본 설정

이슈 기록

수집 옵션

수집 모드

전송 옵션

환경 변수

보안 메모

다음 단계

실행 설정 안전성

​언제 사용하나요

​기본 설정

​이슈 기록

​수집 옵션

​수집 모드

​전송 옵션

​환경 변수

​보안 메모

​다음 단계

​실행 설정 안전성

언제 사용하나요

기본 설정

이슈 기록

수집 옵션

수집 모드

전송 옵션

환경 변수

보안 메모

다음 단계

실행 설정 안전성