LLM Observability с Langfuse: Пълно ръководство за production трейсване (2026)

Актуализирано: 13 юли 2026 г.

LLM observability е практиката да записвате всяко входно съобщение, изходен отговор, междинна стъпка, латентност, брой токени и разход на LLM приложение като структурирани трейсове, така че да може да ги дебъгвате, оценявате и оптимизирате в production. Класическият APM не решава този проблем: той измерва грешки и latency, но не вижда халюцинации, промпт регресии или тихо тройно нарастване на разходите при смяна на модел. В това ръководство ще ви покажа как да инструментирате production LLM стек с Langfuse (open source SDK и платформа), кои метрики трябва да следите и как изглежда таблото, което ще ви се иска да бяхте построили от първия ден.

• LLM observability изисква три обекта, които стандартният APM няма: trace (цялата заявка), span (междинна стъпка) и generation (единично LLM извикване с токени и разход).
• Langfuse v3 инструментира OpenAI и Anthropic SDK с една заменена import линия и добавя автоматично @observe() декоратор за собствени функции, без monkey-patching на LangChain.
• OpenTelemetry GenAI семантичните конвенции станаха де факто стандарт през май 2026 г. след graduation на OTel в CNCF, което прави вашите трейсове преносими между Langfuse, Datadog и Honeycomb.
• Проследявайте p95 и p99 латентност, а не средна. LLM разпределенията са дълги отдясно и средната скрива катастрофални outlier-и.
• За data residency и GDPR self-hosted Langfuse (Docker Compose плюс Postgres, ClickHouse и Redis) остава единственият сериозен open source избор в 2026.
• LLM-as-a-judge оценки върху production трейсове хващат промпт регресии, които offline eval-и пропускат.

Какво е LLM observability и защо APM не е достатъчен

LLM observability е инструменталната практика да записвате входовете, изходите, междинните стъпки и качествените сигнали на всяка заявка към езиков модел, така че да можете да отговорите на въпроси като: „Защо клиент X получи глупав отговор в 14:32?", „Защо разходите ни се удвоиха миналата седмица?" и „Промпт версия v17 регресира ли спрямо v16?". Класическият Application Performance Monitoring (Datadog, New Relic, Sentry в стандартна конфигурация) записва HTTP заявки, exception-и и durations, но третира LLM извикването като непрозрачен black box.

Проблемът е прост: вашият код може да е буг-фрий и приложението пак да е счупено. Моделът може да е халюцинирал, retriever-ът може да е върнал ирелевантни chunk-ове, промпт template-ът може да регресира след последното редактиране, agent loop-ът се завърта в цикъл, или разходите тихо се тройно увеличиха, след като някой е сменил gpt-4o-mini с gpt-4o. Никое от тези не се появява като exception. Появяват се като влошено качество, растящи сметки и бавни отговори. Симптоми, които можете да диагностицирате само ако сте записали входовете, изходите, междинните стъпки и качествените сигнали на всяка заявка.

Честно казано, в моя опит с production LLM апликация с около 2M извиквания на седмица, три класа инциденти оправдават сами по себе си цялата observability инвестиция. Първо, промпт регресии след „безобидна" редакция. Второ, retrieval collapse, когато re-ranker връща null и системата тихо fallback-ва към BM25. И трето, cost drift, когато нов feature изпраща 40k токен контекст всяка заявка. Без трейсове тези проблеми се откриват от support ticket-и. С трейсове те се появяват като аларма 15 минути след deploy.

Как работят trace-ове, span-ове и generation-и

Langfuse моделира всяко production извикване като йерархично дърво от три типа обекти. Разбирането на разликата между тях е ключово за smart инструментиране, така че нека ги разгледаме един по един.

Trace

Trace е коренният обект. Той представлява една логическа заявка от гледна точка на потребителя. Може да е чат съобщение, API call към /generate, или batch job. Всеки trace има user_id, session_id, метаданни (environment, версия на приложението, feature flag стойности) и агрегати за latency, разход и токен консумация.

Span

Span е междинна стъпка в рамките на trace. Типични span-ове: retrieval стъпка, re-ranking, validation с Pydantic схема, guardrail проверка, инструментален call към външно API. Span-овете могат да са влагани, а parent-child релациите изграждат дървото, което виждате в Langfuse UI.

Generation

Generation е специализиран span за LLM извикване. Освен обичайните полета, generation записва: model, input messages, output completion, usage (prompt_tokens, completion_tokens, total_tokens), cost в USD и finish_reason. Langfuse автоматично изчислява разхода, ако знае модела, а базата от цени се обновява от общността.

Инсталация на Langfuse: self-hosted срещу cloud

Langfuse има три deployment опции: managed cloud (EU и US региони), Docker Compose за single-node self-host, и Kubernetes Helm chart за production self-host. За production LLM tracing със сериозен обем препоръчвам да започнете с cloud за първите 1–2 месеца, докато уточните инструменталната стратегия, и после да мигрирате към Helm, ако имате compliance изискване.

Self-hosted Docker Compose (development)

# Клониране на официалното repo
git clone https://github.com/langfuse/langfuse.git
cd langfuse

# Стартиране на стека (Postgres + ClickHouse + Redis + MinIO + web)
docker compose up -d

# Проверка на health-а
curl http://localhost:3000/api/public/health

След стартиране Langfuse UI е достъпен на http://localhost:3000. Регистрирайте първи потребител, създайте организация и проект, и генерирайте public/secret API ключове от Settings → API Keys.

Production Kubernetes с Helm

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update

# Values файл със self-host ключове и external Postgres
cat > values.yaml <<'EOF'
langfuse:
  nextauth:
    secret: "your-32-char-secret"
  salt: "your-salt"
  encryptionKey: "your-64-char-hex-key"
postgresql:
  deploy: false
  auth:
    existingSecret: langfuse-postgres
clickhouse:
  deploy: true
  auth:
    password: "your-clickhouse-password"
redis:
  deploy: true
EOF

helm install langfuse langfuse/langfuse -f values.yaml -n langfuse --create-namespace

Managed cloud (най-бърз старт)

Ако нямате data residency ограничения, регистрирайте безплатен акаунт на cloud.langfuse.com (EU) или us.cloud.langfuse.com. Free tier дава 50 000 наблюдения на месец и unlimited членове на екипа, което е предостатъчно за prototype и малки production приложения.

Инструментиране на OpenAI и Anthropic извиквания

Langfuse Python SDK v3 предлага три пътя за инструментиране: (1) drop-in replacement за OpenAI SDK, (2) @observe() декоратор за собствени функции, и (3) manual context managers за пълен контрол. За 90% от случаите замяната на import-а е всичко, което ви трябва.

OpenAI: drop-in replacement

import os
from langfuse.openai import openai  # заместете стандартния import
from langfuse import observe, get_client, propagate_attributes

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"

langfuse = get_client()

@observe()
def answer_customer_question(question: str, user_id: str) -> str:
    # propagate_attributes прикрепя user_id и session_id
    # към всяка nested generation автоматично
    with propagate_attributes(
        user_id=user_id,
        session_id=f"chat-{user_id}",
        tags=["prod", "support-bot"],
        metadata={"env": "production", "app_version": "1.4.2"},
    ):
        response = openai.chat.completions.create(
            name="support-answer",   # името се появява в Langfuse UI
            model="gpt-4o-mini",
            messages=[
                {"role": "system", "content": "You are a concise support agent."},
                {"role": "user", "content": question},
            ],
            temperature=0.2,
        )
        return response.choices[0].message.content

if __name__ == "__main__":
    print(answer_customer_question(
        "Как да ресетна паролата си?",
        user_id="user_42",
    ))
    langfuse.flush()   # задължително в short-lived процеси (Lambda, cron)

Резултатът: в Langfuse UI виждате trace answer_customer_question с child generation support-answer, който съдържа пълния промпт, отговора, 187 prompt токена, 34 completion токена и разход $0.000058. Изпуснатият flush() в Lambda ми е коствал един цял ден за дебъг, така че наистина не го пропускайте.

Anthropic: чрез OpenTelemetry auto-instrumentation

Тъй като Langfuse няма drop-in wrapper за Anthropic SDK, използвайте openllmetry auto-instrumentation, което емитира стандартни OTel GenAI спанове, консумирани от Langfuse.

pip install anthropic opentelemetry-instrumentation-anthropic \
    opentelemetry-exporter-otlp-proto-http

# Настройка на OTLP endpoint към Langfuse
export OTEL_EXPORTER_OTLP_ENDPOINT="https://cloud.langfuse.com/api/public/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic $(echo -n pk-lf-...:sk-lf-... | base64)"

from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
from anthropic import Anthropic

AnthropicInstrumentor().instrument()  # активира auto-tracing

client = Anthropic()
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Обобщи в едно изречение."}],
)

Този шаблон работи еднакво добре за Google Vertex AI, Cohere, Mistral и локални vLLM инстанции. Всеки OTel-съвместим доставчик е supported. Ако вече използвате структурирани изходи с Pydantic, декораторът улавя и schema validation грешките като span атрибути, което е доста удобно за root cause анализ.

Проследяване на разход, латентност p95/p99 и токени

След като инструментирате приложението, следва най-важната част: кои метрики да следите и на какви прагове да алармирате. Ето минималният набор от dashboards, които държа отворени 24/7.

1. Latency percentiles (p50/p95/p99)

Не следете средна латентност. LLM разпределенията са heavy-tailed, тоест 90% от заявките връщат за 800 мс, но останалите 10% могат да отнемат 15 секунди, което съсипва UX. Setup-нете alert-и на: p95 > 3 секунди за chat интерфейс, p99 > 10 секунди за background job. В Langfuse тези percentiles са пряко достъпни в Metrics таб-а без нужда от external query.

2. Cost per user per day

Групирането на разход по user_id хваща две неща едновременно: (a) power users, които оправдават premium tier, и (b) abuse patterns, където един акаунт консумира $200 за 24 часа. За SaaS с per-seat pricing, ако top 1% потребители консумират 60% от разходите, вашият бизнес модел просто не работи. Трябва usage-based pricing.

3. Token usage по модел и endpoint

Разделяйте prompt tokens и completion tokens. Prompt token-ите обикновено са 3–5x по-евтини от completion при повечето модели, но 10x повече на брой при RAG приложение. Ако видите, че prompt_tokens/completion_tokens ratio се измества драстично след deploy, значи някой е разширил context window-а, без да е осъзнал последствията.

4. Cache hit rate (ако използвате prompt caching)

Anthropic prompt caching и OpenAI cached inputs могат да намалят разходите с 50–90% при повторяемо system prompt съдържание. Ако cache hit rate падне под 60%, промените са преминали TTL прага или някой е модифицирал system prompt-а и invalidate-нал cache-а.

# Пример Grafana alert правило върху Langfuse ClickHouse
- alert: LLMHighP99Latency
  expr: |
    quantile(0.99, langfuse_generation_latency_seconds{env="production"}) > 10
  for: 5m
  annotations:
    summary: "p99 LLM latency > 10s за последните 5 минути"
    dashboard: "https://langfuse.example.com/project/xyz/metrics"

Langfuse срещу LangSmith, Helicone и Arize Phoenix

Пазарът на LLM observability през 2026 г. се консолидира около четири сериозни платформи. Ето сравнение на дименсиите, които реално влияят на избора:

Характеристика	Langfuse	LangSmith	Helicone	Arize Phoenix
Лиценз	MIT (open source)	Commercial	Open source proxy	Elastic 2.0
Self-host	Да, безплатно	Не	Да	Да, безплатно
Setup метод	SDK или OTel	SDK (LangChain-native)	Proxy URL смяна	OpenInference OTel
Eval дълбочина	Средна (LLM-as-judge)	Средна	Ниска	Висока (50+ метрики)
Стартова цена	Безплатно (self-host)	$39/seat/месец	Безплатно (10k req/месец)	Безплатно
Най-подходящ за	Data residency, GDPR	LangChain/LangGraph екипи	Бърз drop-in setup	RAG debugging
Prompt versioning	Да, native	Да, native	Не	Ограничено

Кога Langfuse: ако имате GDPR или data residency изисквания и искате open source, който може да е ваш forever. Ако сте в Европа, това често е решаващият фактор. Langfuse беше придобит от ClickHouse Inc. през първата половина на 2026 г., което засили финансирането, но остави MIT лиценза непокътнат.

Кога LangSmith: ако вашето приложение е дълбоко в LangChain или LangGraph и цените agent graph визуализация. LangSmith е най-бързият път до работещи трейсове за LangChain екипи, но носи най-високия vendor lock-in риск.

Кога Helicone: ако имате прости request/response нужди и искате най-бърз setup, само една смяна на base URL. Не е подходящ за multi-step agent-и, защото няма истинска span йерархия.

Кога Arize Phoenix: ако основното ви предизвикателство е RAG качество (embedding drift, retrieval релевантност, document attribution). Phoenix идва с 50+ research-backed метрики за faithfulness, relevance и hallucination detection.

Оценки в production: LLM-as-a-judge и датасети

Observability без evaluation е обикновен log aggregator. Знаете какво се е случило, но не и дали е било правилно. Langfuse позволява прикрепяне на scores към всеки trace, генерирани от три източника: (1) LLM-as-a-judge автоматични оценители, (2) експлицитен user feedback (thumbs up/down), и (3) manual annotation queue за human review.

from langfuse import get_client
langfuse = get_client()

# LLM-as-a-judge конфигурация в UI:
# 1. Създайте нов Evaluator в Settings -> Evaluators
# 2. Изберете модел (gpt-4o или claude-opus-4-8)
# 3. Дефинирайте prompt template с {{input}} и {{output}} слотове
# 4. Задайте изходна схема: score (0-1) + reasoning

# Програматично създаване на score от външен eval runner
langfuse.create_score(
    trace_id="abc-123",
    name="answer-faithfulness",
    value=0.87,
    comment="Grounded in retrieved context; no hallucination detected.",
)

За задълбочено сравнение на eval frameworks вижте нашето ръководство за LLM оценка с Ragas, DeepEval и Promptfoo. Langfuse интегрира с всяко от тях като score exporter.

Датасети: превръщане на production трейсове в regression тестове

Най-подценяваната feature на Langfuse, честно казано: можете да маркирате production trace като „edge case" и да го добавите към dataset. При следваща промяна на промпта стартирате dataset run срещу новата версия и виждате side-by-side дали качеството е регресирало. Това е единственият надежден начин да предотвратите промпт регресии, които guardrail-и няма да хванат.

OpenTelemetry GenAI конвенции и защо избягват vendor lock-in

През май 2026 г. OpenTelemetry graduated в CNCF и с това превърна GenAI семантичните конвенции в де факто стандарт за LLM observability. Ключовите атрибути, дефинирани в официалната OTel GenAI spans спецификация, включват:

• gen_ai.system, доставчик („openai", „anthropic", „vertex")
• gen_ai.request.model, конкретен модел („gpt-4o-mini")
• gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
• gen_ai.request.max_tokens, gen_ai.request.temperature
• gen_ai.response.finish_reasons
• gen_ai.agent.id, gen_ai.agent.name за agent спанове

Практическото значение е важно: ако инструментирате с OTel-съвместим SDK (Langfuse, OpenLLMetry, OpenInference), трейсовете ви са преносими към Datadog, Honeycomb, New Relic и всеки друг OTel backend. Не сте заключени в един vendor. Ако утре Langfuse изчезне (не се очаква, но допускаме), префокусирайте OTLP exporter-а към друг backend и продължавате. За справка препоръчвам Langfuse GitHub repo, което документира кои OTel атрибути се mapпват на native Langfuse полета.

Production checklist: dashboard-ът, който ще ви се иска да бяхте построили първо

След три production LLM deployment-а, ето точния набор от дашборди и алерти, които препоръчвам да имате готови преди първия production трафик. Не после. Обещавам, ще си спестите доста безсънни нощи.

Задължителни дашборди

1. Latency p50/p95/p99 по endpoint и модел, refresh на 1 минута.
2. Cost per hour с 30-дневна проекция и седмичен baseline overlay.
3. Token usage split, prompt vs completion tokens по модел.
4. Error rate по тип: rate_limit, context_window_exceeded, safety_refusal, timeout.
5. Cache hit rate, ако използвате Anthropic или OpenAI prompt caching.
6. Faithfulness score distribution, LLM-as-a-judge running eval на 5% sample.
7. User feedback rate, thumbs up/down groupнат по нов feature или промпт версия.

Задължителни алерти

• p99 latency > 10s за 5 минути
• Error rate > 2% за 3 минути
• Hourly cost > 150% от 7-дневната mediana
• Cache hit rate < 60% за 15 минути
• Faithfulness score p10 пада с > 15% ден-към-ден

Data retention и sampling

За production с над 500k заявки на ден пълното capture на input/output е скъпо и повдига privacy въпроси. Sample на 10% от нискорисковите trace-ове, но пазете 100% от: (a) заявки с грешки, (b) заявки с user feedback, (c) заявки, маркирани от guardrail-и, и (d) заявки от beta feature flag-и. В Langfuse това се конфигурира чрез sample_rate параметър на SDK ниво или чрез tags-базирано routing.

Често задавани въпроси

Какво представлява LLM observability?

LLM observability е практиката да записвате пълните входове, изходи, междинни стъпки, латентност, брой токени и качествени сигнали на всяка заявка към езиков модел като структурирани трейсове. Разликата от APM: LLM системите са недетерминистични и token-priced, така че трябва да третирате prompt, response и quality scores като first-class обекти, не като opaque payload.

Langfuse безплатен ли е и има ли self-hosted опция?

Да. Langfuse core е MIT лицензиран и напълно self-hostable чрез Docker Compose или Kubernetes Helm chart. Managed cloud (cloud.langfuse.com) има free tier с 50 000 наблюдения на месец и unlimited членове на екипа. Само enterprise SSO, audit logs и SLA са зад платено ниво.

Как да проследявам LLM разходите в production?

Инструментирайте всяко LLM извикване като Langfuse generation, което автоматично записва model, input и output tokens. Langfuse изчислява USD разход от вградената база с цени, обновявана от общността. За cost-per-user анализ propagate-нете user_id като trace атрибут и групирайте в Metrics tab по потребител.

Каква е разликата между trace, span и generation в Langfuse?

Trace е коренният обект, тоест една логическа заявка (напр. едно чат съобщение). Span е междинна стъпка (retrieval, validation, tool call). Generation е специализиран span за LLM извикване, който записва model, prompt/completion токени и разход. Едно trace има много span-ове и generation-и, организирани йерархично.

Langfuse съвместим ли е с OpenTelemetry?

Да. Langfuse v3+ приема OTLP спанове през /api/public/otel endpoint и следва GenAI семантичните конвенции на OpenTelemetry. Това означава, че можете да инструментирате с OpenLLMetry или OpenInference SDK-и и да изпращате към Langfuse, Datadog или Honeycomb с една смяна на OTLP endpoint-а, без vendor lock-in.

Кое е по-добро: Langfuse или LangSmith?

Зависи от stack-а. LangSmith е най-бърз за екипи, дълбоко в LangChain или LangGraph, с първокласна graph visualization. Langfuse е по-добър за open source, self-hosting, data residency (GDPR) и не-LangChain стекове. Ако използвате LangChain и cloud е ок, изберете LangSmith. Ако имате compliance изисквания или искате forever open source, изберете Langfuse.