Build- ja runtime-lokit: Dockup-julkaisujen vianmääritys

Build- ja runtime-lokit vastaavat eri kysymyksiin. Build-lokit kertovat, miten lähdekoodista muodostui image ja miksi prosessi epäonnistui. Runtime-lokit kertovat, mitä rakennettu sovellus teki sen jälkeen, kun container tai Kubernetes-workload käynnistyi.

Väärän lokivirran lukeminen tuhlaa aikaa. Puuttuva riippuvuus imagen muodostamisen aikana ei koskaan näy runtime-lokeissa, kun taas käynnistyksen yhteydessä kaatuvalla onnistuneesti rakennetulla imagella voi olla täysin puhtaat build-lokit.

Mitä eroa build- ja runtime-lokeilla on?

Valitse lokivirta julkaisuvaiheen perusteella:

Vaihe	Tyypillinen tila	Oikea loki	Yleiset virheet
Kloonaus	cloning	Build	Repository-yhteys, branch
Riippuvuuksien asennus	building	Build	Lockfile, registry, paketti
Käännös/bundlaus	building	Build	Type-virheet, muisti, puuttuvat tiedostot
Imagen käynnistys	deploying	Runtime ja health	Käynnistyskomento, portti, oikeudet
Käynnissä oleva palvelu	running	Runtime	Poikkeukset, riippuvuuksien käyttökatkot
Readiness-tarkistus	deploying	Runtime ja health-asetukset	Väärä polku, hidas käynnistys

Lue viimeisin build-tuloste:

dockup logs production/api --build --json

Lue käynnissä olevan palvelun runtime-tuloste:

dockup logs production/api --json

Pyydä lisää runtime-rivejä, jos tarvittava tapahtuma on vanhempi:

dockup logs production/api -n 500 --json

JSON-vastaus yksilöi kohteen ja lokityypin, mikä auttaa agenttia välttämään toisiinsa liittymättömien lokivirtojen yhdistämisen.

Miten dockup logs --build --follow toimii?

Follow-tila välittää uudet rivit pollaamalla nykyistä snapshotia:

dockup logs production/api --build -f --json

JSON-tilassa tuloste on NDJSON-muotoa: yksi objekti riviä ja batchia kohden. Kuluttaja voi käsitellä jokaisen rivin vaiheittain.

Viimeinen batch ilmoittaa buildin lopputuloksen. Komento päättyy automaattisesti, kun julkaisu onnistuu tai epäonnistuu, ja epäonnistuessaan palauttaa nollasta poikkeavan exit-koodin. Siksi se sopii agentille tai CI-työlle ilman erikseen kirjoitettua tilasilmukkaa.

Runtimen follow toimii samalla tavalla:

dockup logs production/api -f --json

Jokainen batch sisältää kentän restarted. Kun restarted:true, container käynnistyi uudelleen tai säilytetty lokipuskuri kiertyi, joten Dockup lähettää koko nykyisen snapshotin uudelleen sen sijaan, että pudottaisi rivejä hiljaisesti.

Oletuspollausväli on 2 sekuntia. Käytä dokumentoitua --interval-valitsinta vain, jos väliä on tarpeen muuttaa.

Miten epäonnistunutta buildia selvitetään?

Aloita julkaisun lopullisesta tuloksesta:

dockup deploy production/api --wait --json

Kun komento päättyy tilaan deploy_failed, hae build-loki ja etsi ensimmäinen syyvirhe viimeisen ketjuuntuneen virheilmoituksen sijaan.

Hyödyllinen etenemisjärjestys on:

1. Vahvista kohde ja julkaisun tunniste.
2. Tunnista kloonaus-, asennus-, käännös- tai image-vaihe.
3. Etsi ensimmäinen virhe, jota ei yritetä uudelleen.
4. Vertaa build-menetelmää repositoryn tarkoitukseen.
5. Toista prosessi puhtaasta kloonista, jos mahdollista.
6. Tee yksi kohdennettu muutos.
7. Julkaise uudelleen valitsimella --wait.

Yleisiä Nixpacks-virheitä ovat tunnistamaton projektin juurihakemisto, puuttuva lockfile, puuttuva tavanomainen käynnistysskripti tai natiivin paketin vaatimus. Yleisiä Dockerfile-virheitä ovat väärä build-konteksti, puuttuva kopioitu artefakti, saavuttamaton base image tai epäonnistuva RUN-ohje.

Nixpacks vs Dockerfile -oppaassa on build-järjestelmän valintakartta.

Älä yritä korjata determinististä build-virhettä kasvattamalla 900 sekunnin aikakatkaisua. Aikakatkaisun muutos auttaa aidosti pitkään buildiin, mutta ei korjaa virheeseen päättynyttä komentoa.

Miten runtime-kaatumista tai health-virhettä selvitetään?

Onnistunut image voi silti epäonnistua ennen liikenteen siirtämistä uudelle versiolle. Tarkista palvelun tila ja runtime-tuloste:

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Etsi seuraavia tilanteita:

• Prosessi päättyy heti käynnistyksen jälkeen.
• Sovellus sitoutuu väärään porttiin.
• Sovellus kuuntelee osoitteessa 127.0.0.1 kaikkien verkkoliitäntöjen sijaan.
• Vaadittu ympäristöavain puuttuu.
• Tietokanta- tai Redis-yhteys epäonnistuu.
• Tiedostojen oikeudet estävät käynnistyksen.
• Health-polku palauttaa muun kuin onnistumista ilmaisevan tilan.
• Käynnistys kestää pidempään kuin määritettyjen yritysten sallima aika.
• Migraatio epäonnistuu tai suoritetaan samanaikaisesti.

Health-asetukset voi tarkistaa tai päivittää:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Älä heikennä health-tarkistusta vain saadaksesi rikkinäisen julkaisun läpi. Jos käynnistys tarvitsee perustellusti enemmän aikaa, muuta käytäntöä todisteiden perusteella ja säilytä endpoint, joka edelleen osoittaa palvelun olevan valmis.

Ympäristömuutokset edellyttävät uutta julkaisua. Jos puuttuva secret korjataan, julkaise uudelleen ja odota; vanhan containerin uudelleenkäynnistys ei ota käyttöön uutta haluttua ympäristöä.

Miten agentin tulisi jäsentää NDJSON-muotoa exit-koodia hukkaamatta?

Agentin tai skriptin tulee lukea jokainen JSON-rivi ja säilyttää samalla prosessin tila. Vältä putkittamasta tulostetta komentoon, joka peittää alkuperäisen exit-koodin ilman pipefail-asetusta.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

pipefail-asetuksen ansiosta epäonnistunut Dockup-komento pitää putken exit-koodin nollasta poikkeavana, vaikka tee suorittuisi onnistuneesti.

Kuluttaja voi tarkastella jokaista objektia erikseen:

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Säilytä alkuperäinen NDJSON-artefakti. Ihmisille luettava ote on hyödyllinen pull requestissa tai häiriötilanteessa, mutta alkuperäiset kentät säilyttävät uudelleenkäynnistysmerkinnät, tilan ja valmistumissignaalit.

Yleiset konekäyttöliittymien periaatteet esitellään oppaassa AI agent CLI design.

Mikä on toistettava julkaisujen vianmäärityksen runbook?

Käytä tätä päätöspolkua:

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Luokittele häiriö tämän jälkeen:

Luokitus	Näyttö	Seuraava toimenpide
Lähdekoodi/build	Virhe build-lokissa	Korjaa repository tai build-määritys
Asetukset	Puuttuva/väärä ympäristömuuttuja tai portti	Korjaa asetukset ja julkaise uudelleen
Readiness	Sovellus toimii, health epäonnistuu	Korjaa endpoint tai perustellusti ajoitus
Runtime-riippuvuus	Yhteyspoikkeus	Tarkista tietokanta, verkko ja tunnistetiedot
Regressio	Edellinen versio toimi	Harkitse tunnetulla tunnisteella tehtävää palautusta
Alustan epävarmuus	Aikakatkaisu, ei lopullista tilaa	Tarkista tila ennen uutta yritystä

Palauta aiempi versio vasta, kun tunnettu aiempi julkaisu on tunnistettu:

dockup rollback <deploymentId> production/api --json

Säilytä epäonnistuneen julkaisun tunniste ja lokit ensin. Palautus palauttaa palvelun saatavuuden, mutta ei selitä juurisyytä.

Zero-downtime deployments -artikkelissa selitetään, miksi epäonnistunut readiness-tarkistus voi suojata tuotantoliikennettä.

Miten tuotantolokeista tehdään hyödyllisiä?

Dockup voi hakea tulosteen, mutta sovellus vastaa lokien laadusta. Suosi jäsenneltyjä, yksittäistä tapahtumaa kuvaavia tietueita, joissa on aikaleimat, vakavuus, request- tai trace-tunnisteet, komponentin nimi ja turvallinen virheen kuvaus.

Älä koskaan kirjaa access tokeneita, tietokantojen URL-osoitteita, salasanoja, kokonaisia authorization-headereita tai toiminnan kannalta tarpeettomia henkilötietoja. Dockupin asetusten secretien maskaus ei poista mielivaltaisen sovellustulosteen salaisuuksia.

Kirjaa turvalliset ja vianmääritykseen sopivat käynnistystiedot:

• Sovelluksen versio tai commit.
• Ympäristön nimi.
• Kuunteluportti.
• Käytössä olevien ominaisuuksien nimet ilman secret-arvoja.
• Tietokantapalvelimen luokka, ei salasanaa.
• Migraatioversio.
• Health-endpointin readiness.

Häiriötilanteen aikajanan malli

Kirjaa seuraavat tiedot:

1. Julkaisun tunniste ja lähdecommit.
2. Julkaisun aloitus- ja päättymisaikaleimat.
3. Ensimmäinen syyvirhe buildissä tai runtimessa.
4. Health-tarkistuksen tulos.
5. Palautuskomento ja julkaisun tunniste.
6. Käyttäjävaikutuksen ajanjakso.
7. Jatkotoimenpiteen omistaja.

Uptime-tiedot lisäävät minuutin tarkkuuden saatavuus- ja vasteaikatiedot:

dockup uptime production/api --hours 24 --json

Tulos sisältää keskimääräisen ja p95-vasteajan. Yhdistä se build- ja runtime-lokeihin, jotta voit erottaa julkaisuhäiriön pidempikestoisesta suorituskykyregressiosta.

Katso ajantasaiset lokivalitsimet Dockup CLI reference -viitteestä ja turvallinen sovelluslokitus security best practices -oppaasta.

Yhdistä lokit julkaisuhistoriaan

Rivi on hyödyllinen vain, jos se voidaan yhdistää oikeaan julkaisuun. Tallenna julkaisun tunniste, commit-hash ja aloitusaika loki-artefaktin yhteyteen. Kun kaksi julkaisua tehdään lähekkäin, pelkät aikaleimat voivat johtaa harhaan.

dockup deployments production/api -n 20 --json

Julkaisuhistoria osoittaa, mikä lähdekoodi oli aktiivinen ja mikä julkaisu saavutti lopullisen tilan. Agentin ei pidä yhdistää runtime-poikkeusta uusimpaan commitiin ennen kuin palvelun tila vahvistaa, että kyseinen commit todella julkaistiin.

Estä lokien kautta tapahtuva secretien paljastuminen

Epäonnistunut yhteys houkuttelee usein tulostamaan koko URL-osoitteen. Kirjaa sen sijaan protokolla, maskattu palvelin, tietokannan nimi ja virheluokka. Tokeneista kannattaa kirjata vain turvallinen fingerprint, joka on luotu ennen tallennusta, jos organisaatiolla on siihen käytäntö.

Tarkista epäonnistuneiden buildien artefaktit ennen niiden jakamista tiimin ulkopuolelle. Package managerin ja Dockerin tulosteet voivat sisältää yksityisten repositoryjen URL-osoitteita, registryn käyttäjänimiä tai komentoargumentteja, vaikka Dockup maskaisi tallennetut ympäristösalaisuudet oikein.

Näin build- ja runtime-lokit ovat riittävän turvallisia yhteistyössä tehtävään vianmääritykseen.

Säilytä suppea todistepaketti

Tallenna jokaisesta epäonnistuneesta julkaisusta julkaisun tuloksen JSON, build-loki, olennainen runtime-ote, palvelun tila ja valittu palautuksen julkaisun tunniste. Paketti on tarpeeksi pieni rutiinikäyttöön ja riittävän kattava, jotta toinen ylläpitäjä voi jatkaa työtä toistamatta epävarmoja muutoksia.

Vahvista korjaus, älä vain uutta buildia

Kun korjattu julkaisu onnistuu, toista epäonnistunut pyyntö tai käynnistystilanne ja seuraa runtime-tulostetta varmistaaksesi, ettei ongelma toistu. Sulje häiriötilanne vasta, kun alkuperäinen oire on poissa, health-tarkistus menee läpi ja odotettu tuotantokäyttäytyminen on havaittu.

Vie asia loppuun

Dokumentoi varmistettu korjaus.

Aloita todennettavasta julkaisusta

Pakota yksi testibuild epäonnistumaan, tallenna sen NDJSON-virta ja exit-koodi ja varmista sitten, että runbook valitsee runtime-lokin sijaan build-lokin.

Aloita ilmaiseksi osoitteessa app.dockup.ai. Free-paketti maksaa 0 dollaria kuukaudessa, sisältää 10 dollarin aloitussaldon ja tukee yhtä workspacea, kolmea tietokantaa ja kolmea julkaisua.

Usein kysyttyä

Mitä eroa Dockupin build-lokeilla ja runtime-lokeilla on?

Build-lokit kattavat kloonauksen, riippuvuuksien asennuksen, käännöksen ja imagen luomisen. Runtime-lokit kattavat käynnistetyn sovelluscontainerin tai podit.

Miten seuraan Dockupin build-lokeja reaaliajassa?

Käytä komentoa dockup logs valitsimien --build ja --follow tai -f kanssa. Valitsimella --json komento tuottaa NDJSON-batcheja ja päättyy, kun julkaisu saavuttaa lopullisen tilan.

Miksi build follow päättyy nollasta poikkeavaan exit-koodiin?

Se säilyttää julkaisun tuloksen. Epäonnistuneen buildin on epäonnistuttava myös kutsuvalle shellille, CI-työlle tai agenttitehtävälle sen sijaan, että lokivirta näyttäisi onnistuneelta.

Mitä restarted:true tarkoittaa runtimen follow-tulosteessa?

Se tarkoittaa, että container käynnistyi uudelleen tai säilytetty puskuri kiertyi, joten Dockup lähetti nykyisen snapshotin uudelleen sen sijaan, että olisi hukannut rivejä hiljaisesti.

Pitäisikö sovelluslokien sisältää ympäristön salaisuuksia?

Ei. Dockup maskaa tallennettujen asetusten lukemisen, mutta se ei voi tehdä sovelluksen tulostamista mielivaltaisista salaisuuksista turvallisia. Rajaa tunnistetiedot pois sovelluksen lokitustasolla.