Paano i-self-host ang Langfuse para i-trace ang AI agent

Bakit kailangang i-trace ang AI agent

Maaari mong i-self-host ang Langfuse upang makita kung ano talaga ang ginawa ng iyong agent sa isang run. Ang Langfuse ay isang open source na LLM (large language model) observability tool. Itinatala nito ang bawat prompt, bawat response ng model, bawat tool call, at bawat token, saka pinagsasama ang mga ito sa iisang trace na maaari mong buksan at basahin. Kapag pinatakbo mo ito sa sarili mong VPS, hindi lumalabas sa server na kontrolado mo ang mga prompt na iyon.

Simple ang dahilan kung bakit ito mahalaga. Hindi mo maaayos ang cost problem o quality problem na hindi mo nakikita. Sinasabi ng provider invoice na apat na beses na mas mataas ang gastos noong Tuesday kaysa noong Monday. Sinasabi ng trace kung aling agent run ang sanhi nito, kung aling prompt ang lumaki sa 40,000 tokens, at kung aling retry loop ang siyam na beses na tumakbo bago sumuko. Ibinibigay ng invoice ang numero. Ipinapakita ng trace ang code na gumawa nito.

Tatlong termino ang gagamitin sa buong guide na ito. Ang trace ay isang end-to-end na run ng iyong agent. Ang observation ay isang hakbang sa loob ng run na iyon: isang span para sa ordinaryong code at isang generation para sa tawag sa model. Ang score ay numerong naka-attach sa isang trace mula sa human review o automated evaluator. Gumagamit ang Langfuse ng OpenTelemetry (OTel), ang vendor-neutral na standard para sa distributed tracing, kaya maaari itong pagdalhan ng instrumentation na mayroon ka na.

Ang aktuwal na pinapatakbo ng self-hosted Langfuse

Ang Langfuse v4 ay hindi isang container lamang. Binubuo ito ng dalawang application container at apat na storage service. Sa isang VPS, lahat ng anim ay tumatakbo sa server mo.

• Ang langfuse-web ang naghahatid ng web interface at ingestion API.
• Ang langfuse-worker ang nagpoproseso ng queue sa background. Pina-parse nito ang mga ingestion batch, kinakalkula ang cost, at pinapatakbo ang nightly retention job.
• Nag-iimbak ang Postgres ng transactional data gaya ng users, organisations, projects, API keys, at prompts.
• Nag-iimbak ang ClickHouse ng mismong trace data, kabilang ang observations at scores. Isa itong column store na ginawa para sa analytical query. Kaya mabilis pa ring sumagot ang dashboard kahit mahigit isang daang milyong row ang laman nito.
• Ang Redis ang queue at cache sa pagitan ng web at worker.
• Nagbibigay ang MinIO ng S3-compatible object storage sa server. Iniimbak nito ang bawat raw incoming event at anumang media na ikinakabit mo.

Naglalathala ang Langfuse ng minimum resource requirement para sa tatlong component na gumagawa ng pangunahing trabaho.

[
  {
    "label": "ClickHouse",
    "cpu_cores": 2,
    "memory_gib": 8
  },
  {
    "label": "Langfuse web",
    "cpu_cores": 2,
    "memory_gib": 4
  },
  {
    "label": "Langfuse worker",
    "cpu_cores": 2,
    "memory_gib": 4
  }
]

Ang ClickHouse lamang ay nangangailangan ng 8 GiB na memory. Ang web container at worker ay nangangailangan ng tig-4 GiB. Ito ang published minimum para sa 3 component na binibigyan ng sizing ng Langfuse. Kailangan pa rin ng memory ng Postgres, Redis, at MinIO. Inirerekomenda mismo ng Docker Compose guide ng proyekto ang machine na may 4 cores, 16 GiB na memory, at humigit-kumulang 100 GiB na storage. Tugma ito sa kalkulasyong iyon at hindi basta may dagdag na allowance.

Huwag itong subukan sa 2 GiB plan. Nagsisimula ang ClickHouse at tumatanggap ng writes nang ilang sandali, ngunit bumabagsak ito habang may background merge dahil naglo-load ang merge ng malalaking bahagi ng table sa memory. Makikita mong iniuulat ng docker compose ps ang clickhouse container bilang restarting, may linyang gaya ng Out of memory: Killed process 1234 (clickhouse-serv) ang dmesg, at nagbabalik ng 500 ang bawat Langfuse dashboard. Kapag mas magaan ang pressure, tatanggihan na lamang ng ClickHouse ang query at ila-log ang DB::Exception: Memory limit (total) exceeded. Sapat ang 8 GiB para sa isang developer na nagpapadala ng ilang libong trace bawat araw. Ang 16 ang dapat mong paghandaan.

I-deploy ang Langfuse gamit ang Docker Compose

I-clone ang repository. Nasa docker-compose.yml ang stack, wiring, at default environment nito.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

Ang bawat value na kailangan mong baguhin ay may markang # CHANGEME sa file na iyon. I-generate muna ang tatlong application secret.

openssl rand -base64 32   # NEXTAUTH_SECRET
openssl rand -base64 32   # SALT
openssl rand -hex 32      # ENCRYPTION_KEY

Ang ENCRYPTION_KEY ay dapat 256 bits na isinusulat bilang 64 hex character. Eksaktong ganito ang inilalabas ng openssl rand -hex 32. Ini-encrypt nito ang mga sensitibong value habang naka-store, kabilang ang anumang LLM provider key na ise-save mo sa instance. Kapag binago mo ito matapos magkaroon ng data, hindi na made-decrypt ang mga row na iyon. Ituring itong permanent mula sa unang boot. Ginagamit ang SALT para i-hash ang iyong Langfuse API key. Kapag binago ito, magiging invalid ang lahat ng key na ginagamit na ng iyong agents.

Pagkatapos, i-set ang POSTGRES_PASSWORD, CLICKHOUSE_PASSWORD, REDIS_AUTH, at MINIO_ROOT_PASSWORD. Lumilitaw ang MinIO password sa apat na lugar: una bilang MINIO_ROOT_PASSWORD, pagkatapos bilang LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY, LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY, at LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY. Kapag may nalaktawan, ire-reject ng MinIO ang client na iyon gamit ang SignatureDoesNotMatch. Lalabas ito sa worker log kahit mukhang healthy pa rin ang web interface. Ang pagpapanatili ng mga value na ito sa isang env file sa halip na sa tracked compose file ang pattern na saklaw sa Docker Compose env files at secrets.

I-pin ang image tags bago magsimula

Ginagamit ng shipped file ang langfuse/langfuse:4 at langfuse/langfuse-worker:4. Nagbabago ang mga tag na iyon. Awtomatikong nagpapatakbo ang Langfuse ng Postgres at ClickHouse migrations sa pagsisimula. Dahil dito, ang isang karaniwang docker compose pull pagkalipas ng ilang buwan ay maaaring maging hindi planadong schema migration sa database na hindi mo na-back up noong umagang iyon. I-pin ang dalawa sa iisang release sa isang docker-compose.override.yml. Ime-merge ito ng Compose sa shipped file, kaya hindi makikialam ang susunod na git pull sa iyong mga edit.

services:
  langfuse-web:
    image: docker.io/langfuse/langfuse:4.3.1
  langfuse-worker:
    image: docker.io/langfuse/langfuse-worker:4.3.1

Ang Version 4.3.1 ang kasalukuyang 4.3 release noong August 2026. Simula noon ay na-release na ang 4.4.0. Suriin ang GitHub releases page ng project. I-pin ang kasalukuyang version sa araw ng deployment, pagkatapos ay ilipat ang numerong iyon nang sinasadya. Naka-pin na sa major version ang storage images sa shipped file: postgres:17, clickhouse-server:25.12, at redis:7. Dapat ay ganoon din ang gawin sa mga ito.

I-start ang stack.

docker compose up -d
docker compose ps
docker compose logs -f langfuse-worker

Pinapatakbo ng first boot ang migrations, kaya maghintay ng isa o dalawang minuto bago may tumugon. Dapat ilista ng docker compose ps ang anim na service na nasa state na running. Kung paulit-ulit na nagre-restart ang worker, nasa log nito ang dahilan: ginagamit ng CLICKHOUSE_MIGRATION_URL ang ClickHouse native protocol sa port 9000, hindi ang HTTP port 8123. Kapag itinuro mo ito sa 8123, mabibigo ito kahit mukhang maayos pa rin ang web container.

Suriin ang health mula mismo sa server.

curl -s "http://localhost:3000/api/public/health?failIfDatabaseUnavailable=true"
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/public/ready

Pinatutunayan lamang ng isang payak na /api/public/health call na buhay ang API process. Sinasadya nitong i-skip ang database upang patuloy na makapag-serve ang service kapag pansamantalang hindi available ang Postgres. Ang failIfDatabaseUnavailable=true form ang dapat gamitin ng monitor. Nagbabalik ito ng 503 kapag hindi maabot ang database. Nagbabalik ang /api/public/ready ng 200 kapag tapos na ang migrations at handa nang tumanggap ng traffic ang container. Pareho itong ordinaryong HTTP check, kaya maaaring bantayan ng Uptime Kuma status page ang mga ito at ipaalam na down ang stack bago ito mapansin ng iyong agents.

Ilagay ang TLS sa unahan at isara ang mga dagdag na port

Ipinapublish ng ibinigay na compose file ang 3000:3000 para sa web container at 9090:9000 para sa MinIO. Naka-bind ang dalawa sa bawat interface. Kapag public ang IP, nangangahulugan ito na sinumang mag-scan sa port 3000 ay makakarating sa sign-up page, at sinumang mag-scan sa 9090 ay makakakonekta sa bucket na naglalaman ng iyong mga raw prompt.

Hindi sapat ang firewall rule para isara ang mga ito. Gumagawa ang Docker ng sarili nitong DNAT rules sa nat table, at sinusuri ang mga ito bago pa makita ng filter rules ng ufw ang packet. Kaya nananatiling bukas ang published port kapag ufw deny 3000 ang ginamit. Maraming naaapektuhan nito kaya mayroon itong sariling guide: bakit nalalampasan ng Docker published ports ang ufw. Sa halip, mag-bind sa loopback sa override file mo.

services:
  langfuse-web:
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NEXTAUTH_URL: https://langfuse.example.com
  minio:
    ports:
      - "127.0.0.1:9090:9000"
      - "127.0.0.1:9091:9001"

Dapat eksaktong public address ang NEXTAUTH_URL, kasama ang scheme, dahil binubuo ng login flow ang callback URL mula sa value na iyon. Kung iiwan mo itong http://localhost:3000 sa likod ng HTTPS proxy, ipapadala ng sign-in round trip ang browser sa address na hindi nito maaabot.

Ngayon, ituro ang reverse proxy sa 127.0.0.1:3000 at hayaan itong maghawak ng certificate. Karaniwang ginagamit ang Traefik sa parehong Compose project, at ang routing labels ay ang mga ipinaliwanag sa pagpapatakbo ng ilang app sa likod ng isang Traefik reverse proxy. Magagawa rin ito ng Caddy sa dalawang linya kung Langfuse lang ang nasa server. I-verify gamit ang curl -sI https://langfuse.example.com/api/public/ready, pagkatapos ay kumpirmahin mula sa pangalawang machine na nagti-time out na ang curl http://YOUR_IP:3000.

May isang caveat sa MinIO. Inihahatid ng Langfuse ang attached media sa browser mo sa pamamagitan ng presigned URLs na tumuturo sa S3 endpoint na iyon. Kaya kung gumagamit ka ng multi-modal traces na may images o audio, hindi maglo-load ang mga attachment kapag loopback-only ang MinIO. Basahin muna ang blob storage configuration page bago ito i-proxy, dahil kailangang tumugma ang endpoint na nakasulat sa presigned URL sa endpoint na ipinapublish mo. Walang epekto ito sa mga plain-text trace.

Gumawa ng account sa unang pagbisita, pagkatapos ay panatilihing sa iyo ang instance. Itakda ang LANGFUSE_ALLOWED_ORGANIZATION_CREATORS sa sarili mong email address para hindi makagawa ng organisation sa server mo ang estrangherong makakarating sa page. Kung nagpapatakbo ka na ng Authentik bilang sarili mong identity provider, tumatanggap ang Langfuse ng standard OIDC connection. Dahil dito, ang mga account ay nadadagdag at natatanggal kasabay ng iba mong app sa halip na manatili sa password list na ang server na ito lang ang nakaaalam.

Ipadala ang una mong trace

Gumawa ng project sa web interface at kopyahin ang public at secret keys nito mula sa project settings. Binabasa ng Python SDK ang tatlong environment variable.

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_BASE_URL="https://langfuse.example.com"

LANGFUSE_BASE_URL ang pangalan ng variable sa SDK v4, na inilabas noong March 2026. Ginagamit ng lumang code at mga lumang guide ang LANGFUSE_HOST. Kung napupunta ang mga trace mo sa Langfuse Cloud sa halip na sa server mo, dahilan ito ng hindi naka-set na base URL, dahil ang default ay tumuturo sa hosted instance.

pip install langfuse opentelemetry-instrumentation-anthropic anthropic

import os
from anthropic import Anthropic
from langfuse import get_client, observe
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor

AnthropicInstrumentor().instrument()
langfuse = get_client()
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

@observe(as_type="tool")
def lookup_order(order_id: str) -> str:
    return f"order {order_id}: shipped"

@observe()
def handle_request(question: str) -> str:
    context = lookup_order("A-1042")
    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=512,
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return message.content[0].text

if __name__ == "__main__":
    assert langfuse.auth_check()
    print(handle_request("Where is my order?"))
    langfuse.flush()

Ang @observe decorator ay nagbubukas ng observation sa paligid ng function, kumukuha ng mga argument nito at return value, at inilalagay ito sa ilalim ng observation na kasalukuyang aktibo. Ang AnthropicInstrumentor ang OpenTelemetry instrumentation para sa Anthropic client. Ginagawa nitong generation ang bawat tawag na messages.create, kasama ang model name, token usage, at latency, nang walang kailangang baguhin sa call site.

Dalawang tawag ang magsasagawa ng pagsusuri para sa iyo. Nagbabalik ang langfuse.auth_check() ng False kapag mali ang keys o base URL, kaya mas mabilis mong matutukoy ang problema kaysa magtaka kung bakit walang laman ang dashboard. Hinaharangan ng langfuse.flush() ang proseso hanggang maipadala ang mga naka-queue na span. Kailangan ito ng mga short-lived process dahil nagba-batch ang SDK sa background, at kapag agad na nag-exit ang script, hindi nito naipapadala ang batch na hindi pa naipadala.

Bakit patuloy na lumalaki ang ClickHouse?

Ang traces ang pinakamabilis lumaking data na karaniwang bina-host ng mga tao. Bawat agent run ay nagsusulat ng isang row para sa bawat step, at buong naka-store ang inputs at outputs. Kaya ang isang chatty agent na may mahahabang prompt ay gumagawa ng mas maraming bytes bawat araw kaysa sa application na mino-monitor nito. Kapag pinabayaan, mapupuno ng ClickHouse ang disk, at kapag puno ang disk, titigil ang ingestion sa halip na bumagal lang.

Dalawang magkahiwalay na bagay ang lumalaki rito, kaya kailangan din ng dalawang magkahiwalay na fix.

Ang una ay ang sarili mong trace data, at ang fix ay ang retention setting. Buksan ang project settings sa web interface at magtakda ng data retention period sa bilang ng mga araw. Tumatanggap ang Langfuse ng minimum na 3 araw. Tuwing gabi, pumipili ang isang job ng mga trace, observation, score, at media asset na mas luma sa window na iyon at dine-delete ang mga ito mula sa ClickHouse at blob storage. Kailangan ng job ng DeleteObject permission sa bucket, na mayroon na ang MinIO root credentials sa default compose file. Permanente ang deletion, kaya mag-configure muna ng blob storage export kung kailangan mo ng long-term history. Huwag manu-manong magsulat ng TTL clauses sa sariling tables ng Langfuse: ang retention job ang nagpapanatiling naka-sync ang ClickHouse at bucket, samantalang ang manual TTL ay isang side lang ang dine-delete.

Piliin ang window batay sa aktuwal mong paggamit. Karaniwang ginagawa ang cost at quality review sa data na ilang araw pa lang, hindi sa data na ilang buwan na. Makatuwirang panimula ang 30 araw para sa maliit na team, at sapat na ang 14 araw kung nagbubukas ka lang ng trace kapag may nasisira.

Ang pangalawa ay ang sariling system log tables ng ClickHouse. Nakakagulat ito sa iba dahil patuloy na lumalaki ang disk kahit naka-configure na ang retention. Nagsusulat ang ClickHouse ng trace_log, text_log, opentelemetry_span_log, metric_log at asynchronous_metric_log para sa sarili nitong diagnostics. Walang TTL ang mga ito bilang default, at hindi kailanman binabasa ng Langfuse. Alamin muna kung saan talaga napunta ang disk space.

SELECT table, formatReadableSize(size) AS size, rows FROM (
    SELECT table, database, sum(bytes) AS size, sum(rows) AS rows
    FROM system.parts
    WHERE active
    GROUP BY table, database
    ORDER BY size DESC
)

Patakbuhin ito gamit ang docker compose exec clickhouse clickhouse-client --password "$CLICKHOUSE_PASSWORD". Kung nasa itaas ng listahan ang system tables, i-disable ang mga ito gamit ang config overlay, dahil mina-merge ng ClickHouse ang bawat file sa /etc/clickhouse-server/config.d/ sa ibabaw ng main config nito kapag nagsisimula.

<clickhouse>
    <trace_log remove="1"/>
    <text_log remove="1"/>
    <opentelemetry_span_log remove="1"/>
    <asynchronous_metric_log remove="1"/>
    <metric_log remove="1"/>
</clickhouse>

I-mount ito at i-restart ang ClickHouse.

services:
  clickhouse:
    volumes:
      - ./clickhouse-config.d/system-logs.xml:/etc/clickhouse-server/config.d/system-logs.xml:ro

Pinipigilan nito ang mga bagong write. Mananatili sa disk ang mga row na naroon na, kaya i-reclaim ang space nang tahasan gamit ang DROP TABLE IF EXISTS system.trace_log at gawin din ang parehong hakbang para sa bawat table na inalis mo. Kung mas gusto mong panatilihin ang diagnostics, ang alternatibo ay magtakda ng aggressive TTL sa bawat table sa halip na remove="1", gaya ng inilalarawan sa Langfuse scaling docs.

May isa pang table na dapat mong malaman. Tinutunton ng blob_storage_file_log ang mga event file na na-upload sa bucket mo. Kung nagtakda ka rin ng lifecycle policy sa bucket, magtakda ng katugmang TTL sa table para hindi magkahiwalay ang kanilang expiration.

ALTER TABLE blob_storage_file_log MODIFY TTL created_at + INTERVAL 30 DAY DELETE;

Maglagay din ng simpleng df -h alert sa data disk. Hindi tuloy-tuloy ang paglaki ng traces. Lumalaki ang mga ito sa araw na nag-release ka ng bagong agent, at hindi dapat ingestion failure ang maging unang palatandaan nito.

Mag-back up ng Postgres at ClickHouse

May tatlong bahagi ang Langfuse backup. Nasa Postgres ang iyong mga user, organisation, project, at API key. Nasa ClickHouse ang mga trace. Nasa MinIO ang mga raw event. Kung Postgres lang ang ire-restore mo, magkakaroon ka ng gumaganang login pero walang history. Kung ClickHouse lang ang ire-restore mo, magkakaroon ka ng history na walang makaka-login para makita.

Ang Postgres ay isang plain pg_dump, na siyang inirerekomenda ng Langfuse backup docs.

docker compose exec -T postgres pg_dump -U postgres postgres \
  | gzip > langfuse-pg-$(date +%F).sql.gz

Mas maingat ang pag-back up sa ClickHouse, dahil hindi consistent na backup ang live data directory na kinopya habang tumatakbo ang mga merge. Ang simpleng paraan sa isang box ay ihinto ang container at i-archive ang volume.

docker compose stop clickhouse
docker volume ls | grep clickhouse
docker run --rm -v langfuse_langfuse_clickhouse_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/langfuse-ch-$(date +%F).tar.gz -C /data .
docker compose start clickhouse

Gamitin ang volume name na ipinapakita ng docker volume ls, hindi ang nakasulat sa YAML. Idinedeklara ng file ang langfuse_clickhouse_data, at nilalagyan ito ng Compose ng project name bilang prefix, kaya ang clone sa directory na tinatawag na langfuse ay gumagawa ng langfuse_langfuse_clickhouse_data. Kapag mali ito, tahimik na gagawa ang docker run ng bagong empty volume, at walang laman ang archive mo.

Isinusulat ng web container ang bawat incoming event sa bucket bago ito iproseso ng worker, kaya ang maikling paghinto ng ClickHouse ay karaniwang nangangahulugan lang na magre-retry ang worker pagkatapos. Gawin ito sa oras na kaunti ang traffic at panatilihing maikli. Para sa mas abalang instance, ang sariling BACKUP DATABASE default TO S3(...) statement ng ClickHouse ay gumagawa ng consistent backup nang hindi ihinihinto ang server. Ang MinIO ang ikatlong bahagi, at sapat na rito ang mc mirror o MinIO replication papunta sa isang off-box bucket. Anuman ang gawin mong backup, ilabas ito sa server. Ito ang gamit ng encrypted restic backups sa isang VPS.

Hindi kailangang i-back up ang Redis. Hawak nito ang queue at cache, kaya kapag nawala ito, ang mga event na kasalukuyang pinoproseso lang ang mawawala at walang mas naunang data.

Totoo ang caveat tungkol sa consistency at mahalagang sabihin ito nang malinaw. Magkaibang oras ginagawa ang dump ng Postgres at ClickHouse, kaya maaaring magkaroon ang restore ng project row na walang trace, o ng mga trace na kabilang sa project na wala na. Tinatanggap ito ng Langfuse, pero gawin ang dalawang dump nang magkalapit ang oras at sa panahong mababa ang traffic. Ang event bucket ang tunay na safety net, dahil ini-store roon ng Langfuse ang bawat incoming event bago ito iproseso.

Mag-restore kahit isang beses sa isang scratch stack. Sa ganitong paraan, malalaman mo ngayon kung mali ang volume name, sa halip na sa oras ng outage.

Mga unang dapat tingnan

May apat na bagay na dapat mong unahin sa unang linggo.

• Gastos bawat trace. Kinukuwenta ng Langfuse ang gastos batay sa model name at token usage, kaya i-sort ang mga trace ayon sa gastos at basahin nang buo ang pinakamahal. Karaniwan, lumaki ang prompt: maaaring buong dokumento ang ipinasa sa context, o conversation history na walang naglilimita sa haba. Kapag nakikita mo na ito, nagiging engineering task sa halip na hula ang pagkontrol sa gastos ng AI agent mo.
• Hati ng token usage sa input at output. Marami at mura ang input tokens, kaunti at mahal ang output tokens, at mas mura pa ang cached input. Ipinaliliwanag din sa kung paano binibilang ang token usage ng Claude Code ang parehong accounting, at naaangkop ito sa anumang agent na ikaw mismo ang sumusulat.
• Latency percentiles. Itinatago ng median ang problema. Sa p95 at p99 karaniwang lumilitaw ang mga timeout, at sa loob ng agent loop, ang mabagal na tool call sa p95 ay napaparami ayon sa bilang ng iterations.
• Mga nabigong tool call. I-filter ang observations ayon sa level ERROR. Ang tool na 5% ng oras ay nabibigo ay maaaring hindi makita sa pinagsama-samang success rate, ngunit malinaw itong makikita sa mga trace, kung saan namo-monitor mong inuulit ng model ang request at pagkatapos ay gumagastos ng tokens upang malampasan ang problema.

Itakda ang retention window at piliin ang dashboard na susuriin mo bawat linggo sa parehong araw ng pag-deploy. Ang observability tool na walang nagbubukas ay database na kalaunan ay pupunuin ang disk.

FAQ

Gaano karaming memory ang kailangan ng isang self-hosted Langfuse?

Maglaan ng 4 CPU cores at 16 GiB na memory, na siyang inirerekomenda ng Langfuse Docker Compose guide para sa isang virtual machine, pati humigit-kumulang 100 GiB na storage. Ang inilathalang minimum ng bawat component ay 8 GiB para sa ClickHouse at 4 GiB bawat isa para sa web at worker containers. Kailangan pa rin ng karagdagang memory ng Postgres, Redis, at MinIO. Kayang patakbuhin ng walong GiB ang instance ng isang developer. Hindi sapat ang dalawang GiB: pinapatay ng kernel ang ClickHouse habang nagsasagawa ito ng background merges, at ipinapakita ng dmesg ang Out of memory: Killed process.

Bakit patuloy na napupuno ang ClickHouse disk ko kahit nagtakda na ako ng data retention?

Ang retention setting ay sumasaklaw lamang sa sariling data ng Langfuse. Hiwalay na nagsusulat ang ClickHouse sa diagnostic tables na trace_log, text_log, opentelemetry_span_log, metric_log at asynchronous_metric_log, at walang TTL ang mga ito. I-query ang system.parts at i-group ayon sa table upang makita kung alin ang pinakamalaki. Pagkatapos, i-disable ang mga hindi ginagamit na table gamit ang remove="1" entry sa isang file sa ilalim ng /etc/clickhouse-server/config.d/, i-restart ang ClickHouse, at i-drop ang mga umiiral na table upang mabawi ang nagamit nang space.

Ano ang minimum na data retention period sa Langfuse?

Tatlong araw. Itinatakda ang retention bawat project sa project settings o sa pamamagitan ng projects API. Tinatanggal ng nightly job ang mga trace, observation, score, at media asset na mas luma sa itinakdang window mula sa ClickHouse at blob storage. Hindi na maibabalik ang mga tinanggal, kaya mag-configure muna ng blob storage export kung kailangan mo ng history na lampas sa window na iyon.

Kailangan ko bang i-back up ang parehong Postgres at ClickHouse?

Oo, dahil magkaibang data ang hawak ng mga ito. Hawak ng Postgres ang users, organisations, projects, at API keys. Hawak naman ng ClickHouse ang mismong trace data. Kapag Postgres lamang ang ni-restore, magkakaroon ka ng instance na maaari mong i-log in ngunit walang laman. I-back up din ang MinIO bucket dahil naglalaman ito ng raw events na sine-save ng Langfuse pagdating ng mga ito. Ito ang pinakamalapit sa source of truth sa stack.

Maaari ko bang ituro ang umiiral kong OpenTelemetry setup sa self-hosted Langfuse?

Oo. Nakabatay ang Langfuse v4 at ang mga v4 SDK nito sa OpenTelemetry, at direktang nag-e-export rito ang Anthropic at OpenAI OTel instrumentations. Sa Python, patakbuhin ang pip install langfuse opentelemetry-instrumentation-anthropic, tawagin nang isang beses sa startup ang AnthropicInstrumentor().instrument(), at itakda ang LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY at LANGFUSE_BASE_URL sa sarili mong host. Kumpirmahin gamit ang langfuse.auth_check() bago maghanap ng nawawalang dashboard.