New Relic

New Relic

LiteLLM을 New Relic과 함께 사용해 APM 텔레메트리와 LLM 메시지를 New Relic으로 보내는 방법을 알려드릴게요. New Relic 콜백을 활성화하면 LiteLLM 서버의 APM 텔레메트리와 AI Monitoring의 LLM 메시지가 모두 New Relic에 보고돼요.

출처: 문서

본문

사전 요구사항 (Prerequisite)

LiteLLM을 New Relic과 함께 사용하려면 New Relic 계정과 라이선스 키가 필요해요. 아직 New Relic 계정이 없다면 무료 티어 계정을 만들 수 있어요.

이 페이지는 프록시 모드에서 New Relic과 LiteLLM을 함께 사용하는 방법을 다뤄요. 애플리케이션에 New Relic Python Agent를 포함해 LiteLLM SDK와 함께 New Relic을 사용할 수도 있어요. New Relic AI Monitoring 문서를 참고해 주세요.

구성 (Configuration)

New Relic LiteLLM 콜백 활성화 (Enable New Relic LiteLLM callback)

New Relic LiteLLM 확장은 콜백으로 구현돼요. 일반적으로 config.yaml 파일로 콜백을 활성화해요. config.yaml로 구성하면 callbacks 목록에 여러 값이 포함될 수 있어요. 목록에 newrelic이 포함되는 한 New Relic LiteLLM 콜백이 호출돼요. 다음 예시는 LiteLLM에서 New Relic 콜백을 활성화해요.

litellm_settings:
  callbacks: ["newrelic"]

LiteLLM 관리 UI로 콜백을 구성할 수도 있어요. 이 옵션을 사용하면 관리 UI 접근을 위해 LiteLLM admin UI 문서를 참고하고 Settings 섹션에 New Relic 콜백을 포함하면 돼요.

필수 환경 변수 (Required environment variables)

New Relic Python Agent는 New Relic에 텔레메트리를 보고하려면 구성이 필요해요. New Relic Python Agent는 구성 파일과 환경 변수로 구성을 지원해요. LiteLLM에서는 환경 변수 사용을 권장하지만 두 옵션 모두 작동해요.

NEW_RELIC_APP_NAME 환경 변수에는 LiteLLM 서버가 New Relic UI에 표시되길 원하는 이름 값이 있어야 해요. NEW_RELIC_LICENSE_KEY 환경 변수 값은 텔레메트리를 보고하려는 New Relic 계정의 라이선스 키예요.

NEW_RELIC_APP_NAME=<app name>
NEW_RELIC_LICENSE_KEY=<license key>

New Relic Python Agent로 LiteLLM 실행 (Running LiteLLM with New Relic Python Agent)

New Relic Python Agent는 애플리케이션 내에서 APM(Application Performance Monitoring) 텔레메트리를 New Relic에 보고하는 데 사용돼요. 아래 단계를 따르면 New Relic 고객은 LiteLLM용 APM 텔레메트리와 LiteLLM 서버의 AI Monitoring 내 LLM 메시지를 모두 받게 돼요.

공식 LiteLLM 컨테이너는 New Relic 콜백을 포함하지만 New Relic Python Agent는 포함하지 않아요. New Relic Python Agent를 포함하는 가장 쉬운 방법은 기존 LiteLLM 이미지 위에 에이전트를 레이어로 얹은 새 컨테이너 이미지를 만드는 거예요. 이렇게 하면 기본으로 사용할 공식 LiteLLM 이미지 버전을 정의할 수 있어요.

New Relic Python Agent가 포함된 LiteLLM 컨테이너를 빌드하려면 다음 Dockerfile, entrypoint.sh, supervisord.conf 파일을 사용하면 돼요. 이 과정은 공식 LiteLLM 컨테이너를 기본 이미지로 사용하고, New Relic Python Agent를 설치하고, 새 entrypoint와 supervisord 구성 파일을 추가해요. 결과 컨테이너는 New Relic에 APM 텔레메트리를 보고하는 New Relic Python Agent와 함께 LiteLLM을 실행해요. 위에서 설정한 콜백과 환경 변수를 사용하면 LLM 메시지도 New Relic에 보고돼요.

컨테이너 이미지를 빌드하려면 Dockerfile, entrypoint.sh, supervisord.conf 파일을 디렉터리에 복사하세요. 이 디렉터리에서 CLI로 다음 명령으로 이미지를 빌드할 수 있어요.

docker build -f Dockerfile -t litellm-newrelic:local .

기본으로 사용할 LiteLLM 이미지 버전을 지정하려면 --build-arg BASE_IMAGE=… 및/또는 --build-arg BASE_TAG=…를 전달해 다른 기본 이미지나 태그를 대상으로 지정할 수 있어요.

BASE_TAG=v1.89.4
docker build \
  --build-arg BASE_IMAGE=docker.litellm.ai/berriai/litellm \
  --build-arg BASE_TAG=${BASE_TAG} \
  -f Dockerfile \
  -t litellm-newrelic:${BASE_TAG} \
  .

출력 이미지 이름은 자신의 이미지 명명 정책에 맞는 docker 이름을 사용하면 돼요. 결과 docker 이미지를 원하는 컨테이너 리포지토리에 푸시하고 싶을 가능성이 높아요.

Dockerfile

Dockerfile은 공식 LiteLLM 컨테이너 위에 추가되는 레이어를 정의해요. 이미지를 실제로 빌드할 때 BASE_TAG를 설정해 사용할 버전을 선택하면 돼요. 이 Dockerfile은 New Relic Python Agent를 설치한 후 New Relic Python Agent와 함께 LiteLLM을 실행하는 새 supervisor·entrypoint 파일을 추가해요.

ARG BASE_IMAGE=docker.litellm.ai/berriai/litellm
ARG BASE_TAG=latest
FROM ${BASE_IMAGE}:${BASE_TAG}

USER root

# Install New Relic agent (ensurepip bootstraps pip in case base image venv omits it)
RUN python -m ensurepip && python -m pip install --no-cache-dir 'newrelic>=12.1.0,<13'

# Copy New Relic-specific configuration files
COPY supervisord.conf /etc/supervisord_newrelic.conf
COPY entrypoint.sh /app/docker/newrelic/entrypoint.sh
RUN chmod +x /app/docker/newrelic/entrypoint.sh

# Override entrypoint to always use newrelic-admin
ENTRYPOINT ["/app/docker/newrelic/entrypoint.sh"]

LABEL org.opencontainers.image.description="LiteLLM with New Relic APM and AI monitoring"

entrypoint.sh

이 entrypoint.sh는 New Relic Python Agent로 래핑된 supervisord 또는 litellm 프로세스를 실행하도록 수정된 LiteLLM 기본 docker/prod_entrypoint.sh의 복사본이에요.

#!/bin/sh
# This entry point is a copy of the litellm docker/prod_entrypoint.sh file
# with these changes:
#
#  - Use the New Relic-specific supervisor file
#  - Wrap the litellm command with New Relic Python Agent

if [ "$SEPARATE_HEALTH_APP" = "1" ]; then
    export LITELLM_ARGS="$@"
    export SUPERVISORD_STOPWAITSECS="${SUPERVISORD_STOPWAITSECS:-3600}"
    exec supervisord -c /etc/supervisord_newrelic.conf
fi

exec newrelic-admin run-program litellm "$@"

supervisord.conf

supervisord를 사용해 LiteLLM을 별도 상태 앱과 함께 실행한다면 이 버전은 메인 LiteLLM 프로세스가 New Relic Python Agent로 시작되도록 보장해요.

# This config is a copy of the litellm docker/supervisord.conf with a change to the `main` program
# to wrap the litellm command with the New Relic Python Agent.

[supervisord]
nodaemon=true
loglevel=info
logfile=/tmp/supervisord.log
pidfile=/tmp/supervisord.pid

[group:litellm]
programs=main,health

[program:main]
command=sh -c 'exec newrelic-admin run-program python -m litellm.proxy.proxy_cli --host 0.0.0.0 --port=4000 $LITELLM_ARGS'
autostart=true
autorestart=true
startretries=3
priority=1
exitcodes=0
stopasgroup=true
killasgroup=true
stopwaitsecs=%(ENV_SUPERVISORD_STOPWAITSECS)s
stdout_logfile=/dev/stdout
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes = 0
stderr_logfile_maxbytes = 0
environment=PYTHONUNBUFFERED=true

[program:health]
command=sh -c '[ "$SEPARATE_HEALTH_APP" = "1" ] && exec uvicorn litellm.proxy.health_endpoints.health_app_factory:build_health_app --factory --host 0.0.0.0 --port=${SEPARATE_HEALTH_PORT:-4001} || exit 0'
autostart=true
autorestart=true
startretries=3
priority=2
exitcodes=0
stopasgroup=true
killasgroup=true
stopwaitsecs=%(ENV_SUPERVISORD_STOPWAITSECS)s
stdout_logfile=/dev/stdout
stderr_logfile=/dev/stderr
stdout_logfile_maxbytes = 0
stderr_logfile_maxbytes = 0
environment=PYTHONUNBUFFERED=true

[eventlistener:process_monitor]
command=python -c "from supervisor import childutils; import os, signal; [os.kill(os.getppid(), signal.SIGTERM) for h,p in iter(lambda: childutils.listener.wait(), None) if h['eventname'] in ['PROCESS_STATE_FATAL', 'PROCESS_STATE_EXITED'] and dict([x.split(':') for x in p.split(' ')])['processname'] in ['main', 'health'] or childutils.listener.ok()]"
events=PROCESS_STATE_EXITED,PROCESS_STATE_FATAL
autostart=true
autorestart=true

LiteLLM 소스에서 실행 (Running from LiteLLM source)

LiteLLM 소스는 의존성 관리에 uv를 사용해요. LiteLLM의 New Relic 통합을 실행하려면 먼저 New Relic Python Agent를 로컬에 설치하세요. 가장 쉬운 방법은 uv로 설치하는 거예요.

make install-proxy-dev
uv pip install 'newrelic>=12.1.0,<13'

그런 다음 소스에서 New Relic Python Agent와 함께 litellm을 로컬로 실행할 수 있어요. 명령 끝에 --config config.yaml이나 --debug 같은 필요한 추가 옵션을 붙이면 돼요.

uv run newrelic-admin run-program litellm

검증 (Verification)

LiteLLM 컨테이너 로그

New Relic 콜백이 초기화되면 초기화와 LLM 콘텐츠 기록 활성화 여부를 확인하는 INFO 로그 메시지를 기록해요. INFO 로그 메시지가 보이지 않으면 LITELLM_LOG=INFO 환경 변수를 설정해 활성화하세요. 다음과 같은 형태의 메시지를 찾아보세요:

New Relic AI Monitoring initialized for app: {app-name}, content recording: {True / False}

New Relic AI Monitoring

New Relic AI Monitoring으로 LLM 메타데이터·콘텐츠가 수신됐는지 확인할 수 있어요. AI Responses 뷰에서 LiteLLM이 응답을 반환한 직후 LLM 요청이 Responses 테이블에 나타나는 것을 볼 수 있어요. LLM 콘텐츠 기록이 활성화되면 LLM 요청/응답 메시지가 Responses 테이블에 나타나요. 테이블의 행을 선택하면 LLM 요청에 대한 더 자세한 내용이 표시돼요. 트레이스 세부 정보는 2~3분 걸릴 수 있어요.

고급 구성 옵션 (Advanced configuration options)

New Relic으로 LLM 메시지 전송 비활성화 (Disable sending LLM messages to New Relic)

다음 방법 중 하나로 New Relic으로 LLM 메시지 전송을 비활성화할 수 있어요.

config.yaml 파일로 New Relic으로 LLM 메시지 전송을 비활성화하는 플래그를 설정할 수 있어요. LLM 메시지를 다른 곳(로그)으로는 보내고 싶지만 New Relic으로는 보내지 않을 수 있도록, New Relic 전용 구성 값이 있어요. config.yaml에 다음을 추가하면 LLM 메시지가 New Relic으로 전송되지 않아요.

litellm_settings:
  callbacks: ["newrelic"]
  newrelic_params:
    turn_off_message_logging: true

New Relic 콜백은 콘텐츠 기록을 비활성화하는 환경 변수 옵션도 읽어요. 이 환경 변수는 기본값이 true예요. 다음 환경 변수를 false로 설정하면 콘텐츠 메시지 기록을 끌 수 있어요.

NEW_RELIC_AI_MONITORING_RECORD_CONTENT_ENABLED=false

LiteLLM 관리 UI로 New Relic 콜백을 추가하는 경우 폼에 부울 값을 받는 옵션이 있어요. 이 부울 값은 환경 변수와 같은 규칙을 따릅니다(true 또는 비어 있으면 LLM 메시지 기록, false면 콘텐츠 메시지 기록 비활성화).

New Relic 에이전트 구성 (New Relic Agent Configuration)

New Relic Python Agent는 여러 방법으로 구성을 받을 수 있어요. 위에서 보았듯 환경 변수로 에이전트 내 다양한 선택적 구성을 설정할 수 있어요.

환경 변수 대신 사용할 수 있는 에이전트 구성 파일도 있어요. 구성 파일을 선호한다면 구성 파일에 접근할 수 있는지 확인해야 해요. 구성 파일을 가리키도록 다음 환경 변수도 설정해야 해요.

NEW_RELIC_CONFIG_FILE=</path/to/newrelic/configuration_file>

New Relic LiteLLM 확장은 메시지가 New Relic AI Monitoring 기능의 일부로 나타나도록 New Relic에 텔레메트리를 보내요. 이 기능을 사용할 때 다음 구성이 권장돼요. 이 구성들은 환경 변수나 구성 파일로 설정할 수 있어요.

NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_ATTRIBUTE_VALUE=4095
NEW_RELIC_CUSTOM_INSIGHTS_EVENTS_MAX_SAMPLES_STORED=100000

팀별 라우팅 (OTel v2) (Per-team routing (OTel v2))

각 LiteLLM 팀은 자체 수집 라이선스 키를 사용해 자체 New Relic 계정으로 트레이스와 비용 메트릭을 보낼 수 있어요. 키가 구성되지 않은 팀의 요청은 New Relic으로 내보내지지 않아요.

프록시가 다음으로 실행되어야 해요:

LITELLM_OTEL_V2=true

팀 콜백 구성(프록시 관리자 또는 조직 관리자):

curl -X POST 'http://localhost:4000/team/{team_id}/callback' \
  -H 'Authorization: Bearer <maste...key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback_name": "newrelic",
    "callback_type": "success",
    "callback_vars": {
      "newrelic_api_key": "<team ingest license key, 40 chars ending NRAL>",
      "newrelic_region": "us"
    }
  }'

newrelic_region은 us 또는 eu를 받으며 트레이스(OTLP)와 비용 메트릭(Metric API) 모두의 데이터 센터를 선택해요. 키는 암호화되어 저장되고 읽을 때 마스킹돼요. 요청 본문은 newrelic_api_key나 newrelic_region을 제공할 수 없어요. 관리자가 구성한 팀 또는 키 콜백 설정만 적용돼요.

트레이스는 litellm.team.id, litellm.team.alias, litellm.cost.* 속성을 가진 OTLP gen_ai.* 스팬으로 도착해요. 비용 메트릭은 litellm.requests, litellm.cost.usd, litellm.tokens.* 카운트와 litellm.request.duration_ms 요약으로 도착하며 team_id, team_alias, model_group, model, custom_llm_provider, status로 패싯됩니다.

팀 예산은 team_id와 team_alias로 패싯된 두 개의 게이지로 도착해요. litellm.team.max_budget은 팀의 구성된 max_budget이고, litellm.team.remaining_budget은 max_budget에서 팀 지출(그 지출을 만든 요청 포함)을 뺀 값이에요. max_budget이 없는 팀은 어떤 게이지도 보내지 않아요. NRQL에서 SELECT latest(litellm.team.remaining_budget) FROM Metric FACET team_alias로 쿼리할 수 있어요.

팀 자격 증명이 없는 트래픽을 위한 선택적 운영자 수준 폴백:

NEW_RELIC_LICENSE_KEY=<operator ingest key>
NEW_RELIC_REGION=us

LITELLM_OTEL_V2=true이면 newrelic 콜백은 Python 에이전트를 로드하는 대신 OTLP로 내보내요. NEW_RELIC_AI_MONITORING_RECORD_CONTENT_ENABLED=false는 여전히 OTLP 경로에서 메시지 콘텐츠 캡처를 비활성화해요. OTLP 경로는 분산 추적, 대시보드, NRQL, 알림에 공급되며 New Relic AI Monitoring 제품 UI를 채우지 않아요.

지원 (Support)

이 통합에 대한 지원은 New Relic 지원에 문의해 주세요.

더 알아보기 (Learn more)