Diagnostische vlaggen

Diagnostische vlaggen schakelen extra logboekregistratie voor één subsysteem in zonder logging.level globaal te verhogen. Een vlag heeft geen effect tenzij een subsysteem deze controleert.

Hoe het werkt

• Vlaggen zijn hoofdletterongevoelige tekenreeksen, afgeleid uit diagnostics.flags in de configuratie plus de omgevingsoverschrijving OPENCLAW_DIAGNOSTICS, ontdubbeld en omgezet naar kleine letters.
• name.* komt overeen met name zelf en alles onder name. (bijvoorbeeld telegram.* komt overeen met telegram.http).
• * of all schakelt elke vlag in.
• Start de Gateway opnieuw nadat je diagnostics.flags in de configuratie hebt gewijzigd; deze wordt niet dynamisch opnieuw geladen.

Bekende vlaggen

Inschakelen via configuratie

{  "diagnostics": {    "flags": ["telegram.http"]  }}

Meerdere vlaggen:

{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

Omgevingsoverschrijving (eenmalig)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

Waarden worden gesplitst op komma's of witruimte. Speciale waarden:

OPENCLAW_DIAGNOSTICS=0 schakelt vlaggen uit zowel de omgeving als de configuratie uit voor dat proces. Dit is handig om tijdelijk een profilervlag te onderdrukken die in de configuratie is blijven staan, zonder het bestand te bewerken.

Profilervlaggen

Profilervlaggen beheren lichtgewicht tijdmetingen; wanneer ze uitstaan, veroorzaken ze geen overhead.

Schakel voor één uitvoering van de Gateway alle door de profiler beheerde tijdmetingen in:

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

Schakel alleen de profilermetingen voor antwoorddispatch in:

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

Schakel alleen de profilermetingen voor opstarten, tools en threads van de Codex-appserver in:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler schakelt zowel de antwoordprofiler als de Codex-profiler in; gebruik de specifieke vlagnamen om er slechts één in te schakelen.

Of stel dit in de configuratie in:

{  "diagnostics": {    "flags": ["reply.profiler", "codex.profiler"]  }}

Start de Gateway opnieuw nadat je configuratievlaggen hebt gewijzigd. Om een profilervlag uit te schakelen, verwijder je deze uit diagnostics.flags en start je opnieuw, of start je het proces met OPENCLAW_DIAGNOSTICS=0 om elke diagnostische vlag voor die uitvoering te overschrijven.

Tijdlijnartefacten

De vlag timeline (alias: diagnostics.timeline) schrijft gestructureerde timinggebeurtenissen voor opstarten en uitvoering als JSONL, voor externe QA-harnassen:

OPENCLAW_DIAGNOSTICS=timeline \OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \openclaw gateway run

Of schakel deze in de configuratie in:

{  "diagnostics": {    "flags": ["timeline"]  }}

Het uitvoerpad komt altijd uit OPENCLAW_DIAGNOSTICS_TIMELINE_PATH, zelfs wanneer de vlag zelf in de configuratie is ingesteld; er is geen configuratiesleutel voor het pad. Wanneer timeline alleen via de configuratie is ingeschakeld, ontbreken de vroegste tijdmetingen voor het laden van de configuratie, omdat OpenClaw de configuratie dan nog niet heeft gelezen; latere opstartmetingen worden normaal vastgelegd.

OPENCLAW_DIAGNOSTICS=1, =all en =* schakelen de tijdlijn ook in, omdat ze elke vlag inschakelen. Geef de voorkeur aan de specifieke vlag timeline wanneer je alleen het JSONL-artefact wilt en niet elke andere diagnostische vlag.

Voor metingen van vertraging in de gebeurtenislus in de tijdlijn is naast timeline nog een extra expliciete inschakeling nodig: stel OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (of on/true/yes) in naast het inschakelen van de tijdlijn.

Tijdlijnrecords gebruiken de envelop openclaw.diagnostics.v1 en kunnen proces-id's, fasenamen, namen van tijdmetingen, duurwaarden, Plugin-id's, aantallen afhankelijkheden, metingen van vertraging in de gebeurtenislus, namen van providerbewerkingen, de afsluitstatus van onderliggende processen en namen/berichten van opstartfouten bevatten. Behandel tijdlijnbestanden als lokale diagnostische artefacten; controleer ze voordat je ze buiten je computer deelt.

Waar logboeken terechtkomen

Vlaggen schrijven logboekgegevens naar het standaardbestand voor diagnostische logboeken. Standaard:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Benoemde profielen gebruiken /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log; --dev gebruikt bijvoorbeeld openclaw-dev-YYYY-MM-DD.log.

Als je logging.file instelt, gebruik dan in plaats daarvan dat pad. Logboeken zijn JSONL (één JSON- object per regel). Redactie blijft van toepassing op basis van logging.redactSensitive. Zie Logboekregistratie voor het volledige model voor padbepaling, rotatie en redactie van logboeken.

Logboeken extraheren

Lees het nieuwste logboekbestand van het actieve profiel:

openclaw logs --plain# Voorbeeld met benoemd profiel:openclaw --profile work logs --plain

Filter op HTTP-diagnostiek van Telegram:

openclaw logs --plain --limit 5000 | rg "telegram http error"

Filter op HTTP-diagnostiek van Brave Search:

openclaw logs --plain --limit 5000 | rg "brave http"

Of volg het logboek tijdens het reproduceren:

openclaw logs --follow --plain | rg "telegram http error"

Gebruik voor externe Gateways in plaats daarvan openclaw logs --follow (zie /cli/logs).

Opmerkingen

• Als logging.level hoger is ingesteld dan warn, kunnen door vlaggen beheerde logboekberichten worden onderdrukt. De standaardwaarde info is geschikt.
• brave.http registreert verzoek-URL's/queryparameters van Brave Search, antwoordstatus/ timing en gebeurtenissen voor cachetreffers, cachemissers en cacheschrijfacties. De API-sleutel (verzonden als verzoekheader) of antwoordinhoud wordt niet geregistreerd, maar zoekopdrachten kunnen gevoelig zijn.
• Vlaggen kunnen veilig ingeschakeld blijven; ze beïnvloeden alleen het logboekvolume voor het specifieke subsysteem.
• Gebruik /logging om logboekbestemmingen, niveaus en redactie te wijzigen.

Gerelateerd

• Gateway-diagnostiek
• Problemen met de Gateway oplossen