Dyscyplina tłumaczenia błędów
Potok kompilacji Aggrega zgłasza błędy z wielu miejsc — walidatorów schematów, resolvera, konstruktora IR, providerów, silnika szablonów Go oraz bazowych bibliotek YAML / Helm / docker-compose, które providery opakowują. Błędy, które docierają do CLI, zaczynają się od nagłówka w nawiasach kwadratowych, wskazującego do dwóch rzeczy — kategorię, która mówi, którym obszarem należy się zająć (w przypadku większości wartości jest to obszar tworzenia, w którym leży błąd), oraz krótki kod warunku, który zatrzymał kompilację — a po nim następują wskaźnik źródła i komunikat. Jeśli warunek zgłosił plugin, kod jest kwalifikowany pluginem, który go zgłosił, ponieważ ten sam warunek może zgłosić więcej niż jeden plugin. Ta strona opisuje kształt tych danych wyjściowych, aby autorzy mogli bezpośrednio interpretować komunikaty o błędach.
Katalog poszczególnych błędów (każde krytyczne zatrzymanie wraz ze wskazówkami, jak je naprawić) znajduje się w fatal-halts.md. Cztery warstwy walidacji schematów i sposób, w jaki współdziałają kształty ich błędów, opisano w vocabulary/validation-surface.md.
Kategorie błędów
Znacznik kategorii wskazuje, którym obszarem należy się zająć. Większość z nich nazywa powierzchnię tworzenia, na której leży poprawka; pozostałe nazywają obszar, który nie jest niczyim błędem autorskim — pobranie artefaktu, werdykt nadzoru albo zaufanie i podpisywanie — a krótki kod w nagłówku obok kategorii w każdym przypadku identyfikuje konkretny warunek:
[DEVELOPER_ERROR]— błąd dotyczy tworzenia encji Aggregate. Poprawka znajduje się w pliku YAML encji Aggregate lub w części katalogu tworzonej przez dewelopera (wartości encji Component, gniazdauses, dołączenia encji Feature). Przykładowe powierzchnie: zatrzymania resolvera z powodu problemów po stronie encji Aggregate; naruszenia selektorów iappliesTow tym, co zapisano w encji Aggregate.[OPS_ERROR]— błąd dotyczy własnych dokumentów operatora, czyli encji Release i Manifest. Poprawka znajduje się w pliku YAML encji Release (topologia granic, wartości parametrów, dołączenia encji Feature na poziomie encji Release) lub w pliku YAML encji Manifest (przez którą encję Recipe wdrażany jest dany typ i zapisane obok niej powiązania adnotacji). Przykładowe powierzchnie: walidacja schematu encji Release; ewaluacja szablonów ścieżek granic; kolizjesubDirectorymiędzy providerami; odrzucenia mapowań i powiązań adnotacji w encji Manifest; reguła odrzucająca połączenie, które tworzy encja Release, lub dołączenie, które wypełnia ona na połączeniu — selektor gniazda, selektor slotu, slot zadeklarowany przez gniazdo jako wymagany; reguła odrzucająca encję Feature dołączaną wyłącznie przez encję Release, do komponentu lub do granicy —appliesToencji Feature, selektor slotu, zadeklarowany schemat.[CATALOG_ERROR]— błąd dotyczy encji katalogu (Recipe, FeatureRecipe, Component, Feature, Plugin). Poprawka znajduje się w treści katalogu. Przykładowe powierzchnie: reguły kształtu encji Recipe; kontrole krzyżowefeaturesSchemaencji Workload; błędy parsowania szablonów utworzonych w katalogu.[TRANSLATION_ERROR]— błąd dotyczy syntezy po stronie providera (plugin providera próbuje przetłumaczyć encję Workload, wynik valuesMapping lub nakładkę ze źródła na artefakty natywne dla providera). Poprawka zwykle znajduje się w kształcieservices/containers/volumesencji Workload, w wyniku szablonuvaluesMappingencji Recipe lub w strukturze nakładki w trybie źródłowym.[FETCH_ERROR]— błąd dotyczy pobierania przypiętej zależności z rejestru lub zdalnego źródła, a nie żadnej powierzchni tworzenia. Poprawka ma zwykle charakter operacyjny: należy uwierzytelnić się w rejestrze (docker login <registry>), przywrócić łączność lub ponownie przypiąć artefakt, który się zmienił lub został zmodyfikowany (aggrega pull --upgrade --release <release>). Przykładowe powierzchnie: nieznaleziona w rejestrze encja katalogu lub chart; wymagane lub nieudane uwierzytelnienie; niedostępna sieć; skrót artefaktu w pamięci podręcznej niezgodny z plikiem blokady. Błędy pobierania zawierają w komunikacie konkretną wskazówkę naprawczą.[POLICY_ERROR]— kompilację odrzucił plugin polityki dołączony w roli werdyktu nadzoru. Nie jest to błąd powierzchni tworzenia: dane wejściowe są poprawnie sformułowane, ale nie spełniają reguły nadzoru (zgodności, FinOps lub bezpieczeństwa) egzekwowanej przez plugin. Poprawka polega na dostosowaniu tego, co zostało napisane, do egzekwowanej polityki albo na ponownym rozważeniu dołączenia polityki. Komunikat podaje odrzucający plugin i zawiera dostarczony przez niego komunikat reguły.[TRUST_ERROR]— warstwa zaufania i podpisywania odrzuciła operację. Ta kategoria nazywa obszar, a nie powierzchnię tworzenia, i obejmuje dwa sposoby naprawy, które można rozróżnić po krótkim kodzie obok niej. Konfiguracja zaufania jest błędna: polityka zaufania, której nie można odczytać, przypięty korzeń zaufania, którego nie można załadować, polityka bezkluczowa niedeklarująca żadnej zaufanej tożsamości, polityka podpisywania wymagająca podpisu dla publikowanego rodzaju artefaktu lub plugin zapisany jako zaufany dla dołączenia werdyktu, którego konfiguracja już nie dołącza. Ten artefakt nie przeszedł weryfikacji: podpis, który nie weryfikuje się względem kotwicy zaufania, artefakt bez podpisu tam, gdzie jest on wymagany, podpis od rzeczywistego, ale niezaufanego podpisującego lub plugin, którego zapisana zaufana tożsamość nie odpowiada już temu, co zostaje rozwiązane. W pierwszym przypadku poprawka znajduje się w konfiguracji lub w zatwierdzonym zapisie zaufania; w drugim jest to decyzja dotycząca artefaktu — przywrócenie przejrzanego artefaktu albo przejrzenie i ponowne zapisanie tego, co się zmieniło.
Ustalenie dotyczące dołączenia encji Feature podąża za dokumentem, który je zapisał
Encję Feature można dołączyć w każdym z dokumentów — encja Aggregate dołącza ją na komponencie lub podsystemie, encja Release na swoim wpisie dla komponentu lub na granicy — dlatego kategorię ustalenia dotyczącego dołączenia odczytuje się z miejsca, w którym dołączenie zapisano, a nie z komponentu, do którego ono sięga. Ustalenie jest umieszczane przy wpisie features:, który zapisał dołączenie, w tym dokumencie, i przypisywane autorowi tego dokumentu: dołączenie wykonane wyłącznie przez encję Release jest zgłaszane pod własną ścieżką encji Release jako [OPS_ERROR], a wykonane przez encję Aggregate — pod ścieżką encji Aggregate jako [DEVELOPER_ERROR].
[OPS_ERROR E0007] release.yaml at .spec.boundaries.main.components.app.features.metrics selector violation ("component.aggrega.ai/type in (server, worker)", declared by Feature "core/prometheus-exporter", not satisfied by the labels of "app"). Add the labels the Feature's appliesTo requires to this component's type, or attach a Feature whose applicability the component already satisfies.Gdy jedno dołączenie zapisują oba dokumenty — encja Aggregate nazywa encję Feature, a encja Release określa jej rozmiar — ustalenie dotyczące dołączenia jako całości jest umieszczane tam, gdzie nazwano encję Feature, czyli w encji Aggregate. Ustalenie dotyczące jednej części konfiguracji jest umieszczane tam, gdzie tę część zapisano: jej values należą do dewelopera, w encji Aggregate, a jej infra do operatora, w encji Release. Dołączenie utworzone przez rozwinięcie sterowane adnotacjami nie zostało zapisane przez żaden wpis features:, więc ustalenie na jego temat jest umieszczane przy komponencie, w dokumencie deklarującym komponent, jako [DEVELOPER_ERROR].
Wymagany slot pozostawiony pusty to jedyny przypadek, którego nie zapisał żaden dokument. Nie ma dołączenia, na które można wskazać, więc ustalenie pozostaje przy komponencie w encji Aggregate i jest zgłaszane jako [DEVELOPER_ERROR], a jego wskazówka naprawcza wymienia oba dokumenty, ponieważ slot może wypełnić każdy z nich: „Dołącz encję Feature pod tą nazwą, w encji Aggregate lub w encji Release, na komponencie lub w zakresie powyżej niego”.
Edytor stosuje to samo umiejscowienie: ustalenie umieszczone w encji Release jest wyświetlane w dokumencie encji Release, przy kluczu, który je zapisał, a w dokumencie encji Aggregate wcale; ustalenie umieszczone w dokumencie modułu importowanego przez encję Aggregate jest w ten sam sposób wyświetlane w dokumencie tego modułu.
Kształt wyjścia
Wydrukowana diagnostyka zaczyna się od nagłówka w nawiasach kwadratowych i wskaźnika źródła, a komunikat umieszcza w osobnym, wciętym wierszu:
[CATEGORY SHORTCODE] <source> <message>Nagłówek zawiera dwa tokeny, które odpowiadają na różne pytania. Kategoria jest jedną z powyższych i wskazuje, którym obszarem należy się zająć. Krótki kod to litera E i cztery cyfry; określa on dokładny warunek, który zatrzymał budowanie: można go zacytować w zgłoszeniu, wpisać w wyszukiwarkę lub odnaleźć w tabeli wszystkich warunków w sentinels.md. Żadnego z nich nie da się wyprowadzić z drugiego, dlatego drukowane są oba — a tam, gdzie kategoria obejmuje więcej niż jeden sposób naprawy, jak [TRUST_ERROR], to krótki kod mówi, z którym przypadkiem ma się do czynienia.
Kod zgłoszony przez plugin jest kwalifikowany przez plugin, który go zgłosił
Każdy krótki kod wskazuje warunek deklarowany przez Aggrega i żadne dwa warunki nie współdzielą jednego kodu: warunek zadeklarowany pod numerem, który ma już inny warunek, jest odrzucany, zanim kompilator odczyta jakiekolwiek dane wejściowe. Plugin nie przydziela własnych kodów. Gdy zgłasza niepowodzenie, wskazuje jeden z warunków deklarowanych przez Aggrega — jeden z kilku ogólnych warunków opisujących, w jaki sposób plugin zawiódł, albo bardziej szczegółowy, jeśli pasuje — i dostarcza zdanie mówiące, co faktycznie się stało. Dlatego dwa pluginy mogą zgłosić ten sam krótki kod, a gdy tak się dzieje, zgłaszają ten sam warunek.
Kod nie może powiedzieć, który plugin napotkał warunek, dlatego nagłówek zgłaszający warunek zgłoszony przez plugin zawiera tożsamość pluginu bezpośrednio przed kodem:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Kod skrócony jest zawsze ostatnim segmentem — litera E i cztery cyfry, po ostatnim /. Tożsamość wtyczki zawiera własne separatory i może zawierać wersję, dlatego to odczyt od końca, a nie od pierwszego /, pozwala odzyskać kod z dowolnego nagłówka. Wszystko przed tym ostatnim segmentem to wtyczka.
Ostatni segment rozwiązuje się tak jak każdy inny krótki kod, niezależnie od tego, który plugin go zgłosił: wymienia go tabela wszystkich warunków w sentinels.md, a aggrega explain go rozwiązuje. Należy cytować sam ostatni segment — kwalifikator mówi, który plugin napotkał warunek, a nie który to warunek. Plugin, który wskazuje kod niezadeklarowany przez Aggrega — numer, którego nie ma żaden warunek, albo wycofany — nie otrzymuje wydruku tego kodu: kompilacja zatrzymuje się na E0293, kwalifikowanym tym pluginem, a jej komunikat cytuje kod zaproponowany przez plugin, wymienia te ogólne warunki i zachowuje własne zdanie pluginu.
Nagłówek z samym krótkim kodem zgłasza warunek zgłoszony przez samo Aggrega, w tym przypadek, w którym plugin zawiódł i nie wskazał żadnego własnego warunku. Wtedy budowanie zatrzymał ogólny warunek kompilatora dotyczący awarii pluginu, a szczegóły zawiera komunikat pluginu.
Każdego z tokenów może brakować, a brakujący jest pomijany
Nic nigdy nie zastępuje tokenu, którego diagnostyka nie ma — żaden symbol zastępczy ani puste nawiasy. Nagłówek może być skrócony na trzy sposoby i każdy z nich coś mówi:
- Brak krótkiego kodu. Awaria nie wskazuje żadnego własnego warunku Aggrega — najczęściej jest to błąd zgłoszony przez bibliotekę opakowywaną przez kompilator. Nagłówek drukuje samą kategorię, więc nadal wiadomo, którym obszarem się zająć.
- Brak kategorii. Awaria nie ma obszaru, do którego mogłaby odesłać, więc żaden nie jest zgadywany. Nagłówek drukuje sam krótki kod i to kod należy odszukać. Wywołują to dwie sytuacje, które wyglądają podobnie, bo z punktu widzenia użytkownika są podobne — żadna nie mówi, gdzie szukać, a kod mówi, co się stało. Pierwsza to błąd w samym kompilatorze, gdy komunikat to stwierdza i prosi o zgłoszenie; występującym przypadkiem jest niezgodność między własnymi widokami katalogu w kompilatorze. Druga to awaria, która wskazuje warunek, ale nigdy nie przeszła przez obszar przypisujący ją do kategorii, co jest typowym kształtem odmowy zgłoszonej na granicy polecenia. Kategoria nigdy nie jest wymyślana, aby wypełnić lukę, i to jest sens pominięcia, a nie jego ograniczenie: kategoria odpowiada na pytanie „którym obszarem się zająć”, a odpowiedź podana tam, gdzie pytanie jej nie ma, nie jest ostrożną odpowiedzią, lecz błędną, na podstawie której działa się w pierwszej kolejności. Warto też powiedzieć, że odwrotne wnioskowanie nie obowiązuje: nagłówek, który ma kategorię, nie zawsze wskazuje coś, co się napisało, ponieważ
[FETCH_ERROR],[POLICY_ERROR]i[TRUST_ERROR]nazywają obszar, a nie powierzchnię tworzenia. - Brak obu. Nawiasy są całkowicie pomijane, a diagnostyka to sam komunikat. Jest to awaria, która nie wskazuje żadnego własnego warunku Aggrega i nie ma obszaru, do którego mogłaby odesłać: polecenie odrzucające swoje argumenty, plik, którego nie można odczytać, anulowanie lub błąd zgłoszony przez bibliotekę opakowywaną przez kompilator bez żadnego naszego warunku pod spodem. Nie ma nic do odszukania w
sentinels.md, a komunikat to wszystko, co awaria ma do powiedzenia.
Ten sam błąd sprowadzony do jednego wiersza, w formie odpowiedniej dla logów, a nie dla terminala, zawiera kategorię i pomija krótki kod:
[CATEGORY] <source>: <message>Kategoria nieobecna w nagłówku jest nieobecna także tutaj, razem z nawiasami, więc ten wiersz nigdy nie ma postaci [] <source>: <message>. Forma jednowierszowa jest ponownie opakowywana w kolejne ramki w miarę przechodzenia awarii w górę, więc pusty znacznik trafiłby do każdej z nich.
Źródło to ustrukturyzowany wskaźnik — zwykle <file>:<line>:<column>, gdy dostępna jest pozycja w YAML, lub identyfikator logiczny (nazwa encji katalogu, nazwa encji Release, ścieżka granicy), gdy pozycja w pliku nie ma zastosowania. Trzeci kształt, <file> at <key>, pojawia się, gdy wskaźnik zna zarówno dokument, jak i klucz w nim, ale nie zna pozycji bajtowej: plik jest tym, co należy otworzyć, a klucz tym, na co spojrzeć po otwarciu. Komunikat to diagnostyka danego obszaru.
Błąd dotyczący jednej instancji kompilacji — komponentu, komponentu wnoszonego przez moduł albo samego modułu — wskazuje tę instancję po pozycji, jako (instance <name>), więc aggregate.yaml (instance shop) to encja Aggregate deklarująca moduł shop. Gdy błąd nie ma dokumentu, na który mógłby wskazać, instancja występuje samodzielnie jako instance <name>: provider, który zawodzi podczas renderowania komponentu adminer, wypisuje [TRANSLATION_ERROR E0082] instance adminer, a wiersze pod nim zawierają resztę błędu, w tym każdy dokument, który on wskazuje. Nazwa to ta, pod którą encja Aggregate deklaruje komponent; komponent wnoszony przez moduł jest nazywany swoją ścieżką przez moduł, np. shop.cart. Instancja nigdy nie jest wypisywana tam, gdzie powinien być plik, więc to, od czego zaczyna się źródło, jest dokumentem, który można otworzyć, albo jednym z powyższych identyfikatorów logicznych.
Reguła oceniana na gotowym grafie zgłasza w tym trzecim kształcie, a klucz pozwala odróżnić dwa wyniki, gdy sam komunikat nie wystarcza. Reguła tego rodzaju nazywa deklarujący typ komponentu, a nie instancję, więc dwa komponenty jednego typu naruszające tę samą regułę mają ten sam komunikat dotyczący tego samego pliku:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.checkout missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.inventory missing required feature: attach a Feature of the required type to the component ("core/observability/monitoring", required by component type "core/compute/api-server", under the requirement label "monitoring")Klucz jest jedyną częścią, która się różni, i to on wskazuje, który z dwóch komponentów należy edytować. Oba wyniki mają ten sam krótki kod, ponieważ to ten sam warunek, wystąpił dwukrotnie — krótki kod nazywa regułę, a klucz nazywa wystąpienie.
Do tego kształtu należą jeszcze dwa wiersze, dla awarii niosącej kontekst do ich wypełnienia — wyrażenie szablonu, które zawiodło, oraz migawka filarów dostępnych w miejscu awarii:
[CATEGORY SHORTCODE] <source> <message> expression: <the template excerpt that triggered the failure> active pillars: <one line per top-level pillar key in scope at the point of failure>Wiersz expression: zawiera fragment szablonu, który wywołał awarię. Blok active pillars: wymienia klucze filarów najwyższego poziomu dostępne w miejscu awarii, aby autorzy widzieli, co można było odpytać. Oba są pomijane, gdy awaria nie niesie żadnego z nich.
Zagnieżdżone ramki kontekstu
Błąd często przechodzi przez więcej niż jedną powierzchnię w drodze do CLI: faza ładowania opakowuje konkretny błąd encji, który z kolei opakowuje sentinel objaśniający regułę. Każda skategoryzowana ramka w takim łańcuchu jest renderowana — najbardziej zewnętrzna jako nagłówek w opisanym wyżej kształcie, a każda zagnieżdżona ramka jako wcięta kontynuacja caused by: z własnym znacznikiem kategorii, wskaźnikiem źródła i komunikatem. Najbardziej wewnętrzna ramka wskazująca plik jest zawsze widoczna:
[CATALOG_ERROR E0094] aggrega-catalog catalog load caused by: [CATALOG_ERROR] aggrega-catalog/recipe/compose/mariadb-copy/1.0.0/recipe.yaml duplicate entity identity within a single catalog directory (recipe identity "compose/mariadb:1.0.0")Tylko nagłówek zawiera krótki kod, a kontynuacje zawierają wyłącznie swoją kategorię. Warunek jest nazywany raz, w miejscu, w którym czytelnik napotyka błąd; ramki pod znacznikiem caused by: to ten sam błąd widziany z głębszego poziomu, więc powtarzanie jego identyfikatora w każdej z nich dodawałoby wiersze bez dodawania faktów. Blok note: nie jest kontynuacją i nie podlega tej zasadzie — raportuje warunki innych dokumentów, a nie ten sam warunek widziany z głębszego poziomu; omawia go sekcja poniżej. Kod wypisywany przez nagłówek to ten, który nazywa łańcuch — tutaj reguła na samym dole — więc ramka kontekstu fazy na górze nadal identyfikuje warunek leżący pod nią.
Czytając od góry do dołu: faza, która zawiodła, następnie encja (wraz ze ścieżką pliku), która to spowodowała, a potem naruszona przez nią reguła. Zagnieżdżona ramka, która nie wnosi nic ponad ramkę nadrzędną (ta sama kategoria, to samo źródło, komunikat zawarty już w ramce nadrzędnej), jest deduplikowana zamiast powtarzana, a końcowe objaśnienie jest renderowane tylko wtedy, gdy ramki nad nim nie zawierają już jego treści.
Łańcuch sięga głębiej zawsze, gdy błąd przechodzi przez więcej powierzchni w drodze na zewnątrz, a zasada obowiązuje na każdej głębokości. Szablon odrzucony wewnątrz syntetyzowanej encji Workload z encji Recipe przechodzi przez trzy — renderowany węzeł, powierzchnię szablonów encji Recipe i sam szablon:
[CATALOG_ERROR E0060] instance db rendering node "db" caused by: [CATALOG_ERROR] recipe "mariadb" workload template caused by: [CATALOG_ERROR] workload[mariadb] template references a root the render context does not define (template "workload[mariadb]" references ".nosuchroot.database", the render context defines .context, .values, .infra, .locals, .provides, .features, .metadata, .attachment_name, .inject, .inject_raw, .steps, .source, .workload, .boundary)Należy czytać go od góry do dołu jak wcześniej i zwrócić uwagę na trzy rzeczy, które uwidacznia dodatkowa głębokość. Krótki kod pojawia się raz, w nagłówku, niezależnie od liczby następujących po nim kontynuacji. Najbardziej wewnętrzna ramka zawiera zdanie właściwe dla warunku, więc najgłębszy wiersz jest zarówno tym, do którego należy dopasowywać, jak i tym, który mówi, co zmienić. A ramka bez wskaźnika źródła wypisuje wyłącznie swoją kategorię: środkowa ramka powyżej nazywa w komunikacie powierzchnię, na której zawiodła, ponieważ ta powierzchnia jest szablonem, a nie plikiem, i nie ma pozycji, którą można wskazać.
Gdy błąd rozgałęzia się pod ramką — faza zebrała kilka niezależnych naruszeń przed zatrzymaniem — kontynuacja zawiera ich liczbę, a każdy zebrany błąd jest renderowany pod nią, oddzielony tą samą linią ---, której używają opisane niżej łańcuchy wielu błędów:
[OPS_ERROR E0099] recipe resolution caused by (2): [OPS_ERROR] .spec.components.edge no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.edge, "edge", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to it --- [OPS_ERROR] .spec.components.internal no recipe resolved for component/feature instance: add an explicit Manifest mapping for its type (Manifest, at .spec.components.internal, "internal", of type "example/gateway/nginx-reviewed"). no recipe in the catalog implements this type; write one, then map the type to itZebrane błędy pod licznikiem również są kontynuacjami, więc żaden z nich nie powtarza krótkiego kodu nagłówka — dzięki temu rozgałęzienie z tuzinem naruszeń nie wypisuje tuzin razy tego samego identyfikatora.
W całości obowiązuje jedna gramatyka separatorów: --- między błędami równorzędnymi, caused by: między zagnieżdżonymi ramkami kontekstu.
Odrzucony plik katalogu i błąd, który wyjaśnia
Ładowanie katalogu w celu rozwiązania zależności encji Release jest celowo tolerancyjne: plik, którego nie można odczytać, lub dokument Aggrega, którego nie można sparsować ani zindeksować, zostaje odrzucony i odnotowany, zamiast przerywać całe ładowanie. Dzięki temu uszkodzona encja, której dana encja Release nigdy nie dotyka, nie powoduje niepowodzenia niezwiązanej kompilacji.
W konsekwencji odrzucony plik po cichu znika z katalogu — a jeśli encja Release jednak do niego sięga, niepowodzeniem kończy się próba rozwiązania odwołania do tego, co ten plik deklarował. Ten błąd jest konsekwencją odrzucenia, a nie samym odrzuceniem, dlatego raport przedstawia oba w kolejności przyczynowej wszędzie tam, gdzie może dokładnie wskazać odrzucenie:
[CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schema note: this file was skipped at load, so the catalog holds nothing under the identity it declares. This Release reaches that identity, so what failed is the attempt to resolve the reference to it: resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe"Odrzucenie jest na pierwszym miejscu, z własną kategorią i własnym krótkim kodem, ponieważ wskazuje to, na co można zareagować: poprawka polega na dodaniu brakującego implements: w encji Recipe, a nie na czymkolwiek związanym ze sposobem wyszukiwania odwołania w rejestrze. Błąd rozwiązania jest nadal zgłaszany, pod spodem, ponieważ to on mówi, dlaczego ten dokument był w ogóle potrzebny.
Odrzucenie jest na pierwszym miejscu tylko wtedy, gdy dokładnie jeden odrzucony plik deklaruje tożsamość wskazaną przez nieudane odwołanie. Dopasowanie dotyczy tożsamości, którą każdy dokument deklaruje dla siebie — jego rodzaju, nazwy, wersji, a w przypadku recepty także spec.capability, które określa jej zakres — więc odrzucony plik deklarujący to, czego żąda odwołanie, jest plikiem, do którego to odwołanie zostałoby rozwiązane. Wynikają z tego dwie konsekwencje. Odwołanie podające zakres wersji zamiast wersji nie wskazuje żadnego pojedynczego dokumentu, więc niczego nie wyróżnia. A dokument zbyt zniekształcony, by dało się odczytać jego nagłówek, nie deklaruje żadnej tożsamości, więc nigdy nie jest wskazywany jako przyczyna czegokolwiek.
Gdy żaden odrzucony plik nie deklaruje tej tożsamości lub deklaruje ją więcej niż jeden, raport wygląda tak, jak wyglądałby bez zapisu odrzucenia: błąd jest na pierwszym miejscu, a każde odrzucenie jest wymienione pod nim do samodzielnej oceny. Wskazanie niewłaściwego pliku jako przyczyny byłoby gorsze niż niewskazanie żadnego, ponieważ działania zostałyby podjęte na jego podstawie.
[E0105] resolve entity "server-recipe:1.0.0": catalog: tier-3 pull server-recipe:1.0.0: recipe reference must be provider-scoped (<provider>/<name>); an empty provider cannot bind to an OCI location: "server-recipe" note: catalog files skipped at load. A refusal outside this Release's closure is tolerated and never fails a build, so this failure is explained only by a refusal naming something this Release reaches: - Recipe "server-recipe" (catalog/recipes/helm/server.yaml): [CATALOG_ERROR E0215] catalog/recipes/helm/server.yaml: document envelope validation failed (Recipe, at catalog/recipes/helm/server.yaml); 6:1: spec.implements: missing required property: implements. correct the document to match its kind's schemaWarto znać kilka szczegółów tej drugiej postaci, ponieważ każdy z nich odpowiada na pytanie, które blok mógłby w przeciwnym razie nasunąć.
Nagłówek wskazuje błąd, a nie odrzucenie. Krótki kod na górze to ten, który zgłosił błąd rozwiązania, ponieważ to ten błąd jest tu na pierwszym miejscu — żaden odrzucony plik nie został wyróżniony, więc żaden nie otwiera wiersza. Nie towarzyszy mu kategoria, ponieważ nic na tej ścieżce nie przypisało błędu do żadnego obszaru. Nagłówek każdego odrzucenia znajduje się w jego własnym wpisie poniżej i tam należy go czytać.
Wymienione jest każde odrzucenie, nie tylko to istotne. Dojście do tej postaci oznacza, że zapis nie mógł wyróżnić jednego, więc notatka zamiast zgadywać, podaje rozróżnienie: odrzucenie spoza domknięcia tej encji Release jest tolerowane i nie może być przyczyną niepowodzenia, co pozostawia odrzucenie wskazujące coś, do czego sięga encja Release, jako jedyny wpis, który je wyjaśnia. Wpisy należy porównać z tym, czego encja Release faktycznie używa.
Każdy wpis ma własny nagłówek w nawiasach kwadratowych — własną kategorię i własny krótki kod. To jedyne miejsce, w którym krótki kod pojawia się poniżej nagłówka diagnostyki, i nie jest to wyjątek od opisanej wyżej reguły kontynuacji, lecz jej konsekwencja: wpis pod note: nie jest tym samym błędem widzianym z głębszego poziomu, lecz innym stanem zgłoszonym przez inny dokument. Wskazanie jego stanu pozwala wyszukać odrzucenie i poprawić plik, a właśnie temu działaniu ma służyć ten blok.
Odrzucony plik, którego nagłówek był zbyt zniekształcony, by odtworzyć deklarowaną w nim tożsamość, jest wymieniany wyłącznie ze ścieżką. To uczciwe odczytanie dokumentu, do którego nic nie mogło zajrzeć, a ścieżka wystarcza, by otworzyć plik. Plik zbyt zniekształcony, by odczytać choćby jego rodzaj — na przykład taki, który nie parsuje się jako YAML — jest wymieniany w ten sposób, gdy deklaruje apiVersion Aggrega, czyli zawiera wiersz zaczynający się bez wcięcia od apiVersion: z wartością rozpoczynającą się od aggrega.ai/, wraz z przyczyną podaną przez sam parser: wierszem i tym, czego parser się w nim spodziewał. Plik YAML deklarujący inną apiVersion lub żadnej nie jest dokumentem Aggrega — może to być na przykład szablon chartu albo plik konfiguracyjny trzymany obok encji — więc nigdy nie jest wymieniany, niezależnie od stopnia zniekształcenia.
Plik deklarujący rodzaj, którego nie zawiera żaden katalog, jest wskazywany tylko tam, gdzie wyjaśnia niepowodzenie. Dokument deklarujący apiVersion Aggrega i kind, którego nie zawiera żaden katalog — na przykład błędnie zapisany Componnent — jest pomijany przy każdym wczytywaniu, więc nie jest odrzuceniem i nie figuruje wśród odrzuceń. Gdy odwołanie, które się nie powiodło, prosi o nazwę deklarowaną przez ten plik, a także o jego wersję, jeśli odwołanie ją podaje, raport wskazuje ten plik we własnej notatce pod niepowodzeniem, niezależnie od tego, jako jaki rodzaj odwołanie zostało zebrane — na każdej z powierzchni wymienionych poniżej oraz w aggrega build, niezależnie od tego, czy odczytuje istniejący plik blokady, czy najpierw go wypełnia:
[E0114] resolve: no entity in the catalog matches this URI: entity "<reference>" (referenced from <referring paths>) note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: - Componnent "<name>" (<path>): [CATALOG_ERROR E0371] <path>: catalog document declares a kind a catalog does not hold (kind "Componnent"). a catalog holds Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Aggregate and Plugin documents, and passes over a Workload, a Manifest or a Release; correct the kind, or move the file out of the catalog directoriesNiepowodzenie nadal jest na początku: rodzaj deklarowany przez plik nie wyznacza żadnej tożsamości, więc plik nigdy nie zostaje wskazany jako odrzucenie, od którego zaczyna się raport. Wyjaśnienie, skąd wczytywane są encje lokalne, jest w tym raporcie pomijane, ponieważ plik znajduje się już tam, skąd czyta katalog, a jego przeniesienie by nie pomogło. Plik o rodzaju, którego nie zawiera żaden katalog, deklarujący inną nazwę, niczego w tym niepowodzeniu nie wyjaśnia i nie jest wspominany. aggrega serve, którego komunikaty mają jeden wiersz, umieszcza tę samą notatkę w tym wierszu — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it:, a po niej odrzucenie pliku — i nigdy nie wymienia takiego pliku wśród plików pominiętych przy wczytywaniu; narzędzie describe z aggrega mcp, zapytane o nazwę w kontekście encji Release, również wskazuje ten plik zamiast tego wyjaśnienia. aggrega validate i aggrega lint dla całego katalogu zgłaszają każdy taki plik niezależnie od tego, czy cokolwiek do niego sięga — zob. fatal-halts.md §„A catalog document declares a kind a catalog does not hold (Dokument katalogu deklaruje rodzaj, którego katalog nie zawiera)”.
Niezależnie od otrzymanej postaci błąd zachowuje własną tożsamość. Notatka jest dodawana do błędu, a nie renderowana zamiast niego, a umieszczenie odrzucenia na pierwszym miejscu zmienia tylko to, co czyta się najpierw — stan zgłoszony przez błąd pozostaje więc w obu przypadkach nienaruszony: jego krótki kod nadal jest rozpoznawany, a narzędzie dopasowujące stan nadal go dopasowuje.
Gdy odrzucony dokument jest sam w sobie tym, co raportuje polecenie, odrzucenie jest podawane raz. aggrega inspect <name> ładuje katalog w trybie ścisłym, więc dokument odrzucony przy ładowaniu je zatrzymuje, a wypisywane jest odrzucenie tego dokumentu jako pojedyncza diagnostyka: nagłówek z kategorią i krótkim kodem odrzucenia, dokument jako źródło, a pod nim to, co jest z dokumentem nie tak — w przypadku naruszenia schematu naruszone klucze z wierszami i kolumnami oraz wskazówka. Ładowanie, które je zgłosiło, przeszło przez przeglądany katalog i krok odczytujący plik, ale nie są one wypisywane jako osobne ramki, ponieważ każda ponownie wskazywałaby ten sam dokument bez dodania żadnego faktu. aggrega serve zapytane, do czego odnosi się nazwa, którą deklaruje odrzucony dokument, odpowiada tym samym odrzuceniem tymi samymi słowami w jednym wierszu, a następnie notatką, że plik został pominięty przy ładowaniu. Jak wyżej, stan odrzucenia pozostaje w obu przypadkach możliwy do dopasowania.
Obie postacie docierają wszędzie tam, gdzie wykonywane jest to rozwiązywanie. aggrega build, aggrega pull, aggrega validate --release i aggrega inspect --closure generują je w terminalu, podobnie jak aggrega validate dla pojedynczej encji Recipe, której cel implements nie zostaje znaleziony, a asystent AI połączony przez aggrega mcp otrzymuje ten sam opis z narzędzi build i validate oraz wiodącą odmowę w jednym wierszu z odczytu catalog:// encji deklarowanej przez odrzucony plik. Powierzchnia, z której pochodzi zapytanie, nie zmienia tego, który plik należy otworzyć — wywołujący, który łączy się z aggrega mcp przez HTTP, otrzymuje ścieżkę względem katalogu głównego obszaru roboczego i nie otrzymuje ścieżki spoza obszaru roboczego obsługiwanego przez serwer — a gdy odrzucenie jest na pierwszym miejscu, kontrakt autorski, do którego odsyła odpowiedź, dotyczy rodzaju deklarowanego przez odrzucony dokument, a nie rodzaju nieudanego odwołania.
Klasa błędów koperty dokumentu
Każdy dokument encji — encje katalogu, Aggregates, Manifests, Releases — jest podczas wczytywania, przed parsowaniem typowanym, walidowany względem opublikowanego schematu JSON swojego rodzaju. Dokument, który narusza swoją kopertę (nieznany klucz, brak wymaganego pola, wartość o niewłaściwym kształcie, zakazana konstrukcja, taka jak values: w encji Release), powoduje głośne zatrzymanie z diagnostyką, która najpierw nazywa warunek, następnie rodzaj encji i plik, potem każdy błędny klucz lub kształt wraz z wierszem i kolumną, w których się znajduje, a na końcu wskazuje, co z tym zrobić:
[OPS_ERROR E0215] release.yaml document envelope validation failed (Release, at release.yaml); 12:7: spec.boundaries.main.values: against /$defs/boundary: unexpected property: "values". correct the document to match its kind's schemaDiagnostyka zaczyna się od warunku, nazywa rodzaj i plik, a kończy się wskazówką, co zrobić; każde naruszenie pomiędzy nimi zawiera samo line:column, ponieważ nagłówek już nazwał plik. Każdy błędny klucz jest zgłaszany na jego własnej pozycji, a nie na pozycji zawierającego go bloku, więc wiersz i kolumna wskazują klucz, który należy zmienić. Gdy kształt danej pozycji pochodzi z definicji wielokrotnego użytku w schemacie, diagnostyka nazywa tę definicję po słowie against — powyżej against /$defs/boundary — dzięki czemu jasne jest, względem jakiego kontraktu mierzono klucz, a definicja nie wygląda jak kolejny krok na zapisanej ścieżce klucza. Dokument z kilkoma naruszeniami wymienia każde na jego własnej pozycji, w kolejności kluczy, a raport zatrzymuje się po czterech, podając liczbę pozostałych.
Warto wiedzieć dwie rzeczy o tym, co wskazuje pozycja, ponieważ obie są raczej przydatne niż zaskakujące:
- Brakujący wymagany klucz nie ma własnej pozycji — z definicji nie występuje w dokumencie. Naruszenie wskazuje zamiast tego klucz nadrzędny, czyli miejsce, do którego należy brakujący wpis. Zatem
spec.capability: missing required propertywskazujespec:i właśnie tam należy go dodać. - Klucz, którego nazwa zawiera kropkę — każda etykieta
component.aggrega.ai/…i adnotacjafeatures.aggrega.ai/…— jest zgłaszany na bloku, który go zawiera, a nie na samym wpisie, ponieważ kropki są odczytywane jako kroki w głąb dokumentu. Naruszenie dotyczące etykiety wskazujelabels:.
Gdy naruszenie nazywa klucz, którego w ogóle nie ma w dokumencie — na przykład pominięto cały blok metadata: — pozycja jest pomijana, a nie zgadywana, i naruszenie składa się wyłącznie ze ścieżki klucza i komunikatu. Pozycja, której nie można ufać, jest gorsza niż żadna.
Kategoria wynika z powierzchni tworzenia: [CATALOG_ERROR] dla encji katalogu, [DEVELOPER_ERROR] dla Aggregates, [OPS_ERROR] dla Releases i Manifests. Ta sama bramka działa na każdej powierzchni, która wczytuje encje — aggrega build, aggrega lint, aggrega validate oraz diagnostyki edytora publikowane przez aggrega serve — więc zbędny lub błędnie zapisany klucz jest odrzucany wszędzie tam, gdzie dokument jest po raz pierwszy odczytywany, zamiast zostać po cichu pominięty. Każda z tych powierzchni wyznacza pozycję w ten sam sposób, więc wskazują ten sam klucz, i każda odczytuje zdanie warunku z samego warunku: wiersz podkreślony przez edytor to wiersz, który nazywa terminal, a zdanie, od którego zaczyna się wpis edytora, to zdanie, od którego zaczyna terminal. Obie powierzchnie nie współdzielą natomiast całego komunikatu, i jest to celowe — terminal grupuje wszystkie wyniki pod jednym nagłówkiem i kończy wskazówką dla ścieżki, podczas gdy edytor emituje jeden wpis na wynik, umieszczony na jego własnym kluczu, nie powtarzając ani pliku, do którego jest już przypisany, ani wskazówki, którą w przeciwnym razie powtarzałby przy każdym podkreśleniu. Zbieżna jest więc ta część, po której rozpoznaje się warunek.
Łańcuchy wielu błędów
Gdy pojedyncza kompilacja wykryje wiele niezależnych naruszeń (najczęściej podczas analizy statycznej, w której każde naruszenie selektora i appliesTo jest zbierane, zanim którekolwiek z nich zatrzyma budowanie), błędy są łączone w jeden łańcuch. CLI przechodzi przez łańcuch i renderuje każdy błąd składowy niezależnie, oddzielając je linią poziomej kreski:
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.---[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge2.uses.reviewed_upstream.internal selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.Separator --- jest dosłowny — czytelnicy i dalsze narzędzia mogą dzielić dane wyjściowe według niego, aby wyliczyć połączone błędy. Każdy błąd składowy jest samodzielnym niepowodzeniem, a nie szczegółem sąsiedniego, dlatego każdy ma własny nagłówek: własną kategorię i własny krótki kod, każde tam, gdzie występuje, jak opisuje sekcja o brakujących elementach. Dwa naruszenia jednej reguły podają ten sam krótki kod, jak powyżej; dwa naruszenia różnych reguł podają różne kody.
Odczytywanie błędu od początku do końca
W większości kontekstów tworzenia definicji prefiks kategorii wraz ze wskaźnikiem źródła pozwalają ustalić, co należy poprawić:
| Kategoria | Gdzie wprowadza się poprawkę | Przykładowe przypadki |
|---|---|---|
[DEVELOPER_ERROR] | YAML encji Aggregate | Naruszenia selektora / appliesTo w tym, co zapisała encja Aggregate; niedopasowanie gniazda uses po stronie encji Aggregate; zatrzymania resolvera na definicjach dewelopera. |
[OPS_ERROR] | YAML encji Release / YAML encji Manifest | Szablon ścieżki granicy odwołuje się do nieobsługiwanego pola; subDirectory powoduje kolizję ścieżek; zatrzymania resolvera na definicjach encji Release; połączenie, które łączy encja Release, lub dołączenie, które wypełnia ona na połączeniu, odrzucone przez reguły gniazda lub slotu; encja Feature dołączana wyłącznie przez encję Release, do komponentu lub do granicy, odrzucona przez reguły encji Feature lub slotu; odrzucenie mapowania lub powiązania adnotacji w encji Manifest. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Reguły kształtu encji Recipe; szablon encji FeatureRecipe odwołuje się do pola dostępnego tylko per komponent przy executionScope: boundary; niepowodzenie kontroli krzyżowej featuresSchema encji Workload. |
[TRANSLATION_ERROR] | Workload / wynik valuesMapping / nakładka źródła | Rozwiązywanie portu sondy Helm; kolizja nazw usług compose między granicami; dwóch kontrybutorów compose deklarujących jedną nazwę wolumenu lub konfiguracji najwyższego poziomu z sprzecznymi treściami; niezgodność nazwy chartu w parasolu helm-chart. |
[FETCH_ERROR] | Rejestr / pobieranie zdalnego źródła (operacyjne, nie związane z tworzeniem definicji) | Nie znaleziono artefaktu w rejestrze; wymagane uwierzytelnienie; sieć nieosiągalna; niezgodność skrótu w pamięci podręcznej z plikiem blokady. Poprawka: uwierzytelnić się, przywrócić łączność lub wykonać aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin polityki (reguła nadzoru) | Plugin polityki dołączony w roli werdyktu nadzoru odrzucił złożony build na podstawie egzekwowanej przez siebie reguły. Poprawka: spełnić egzekwowaną politykę lub ponownie rozważyć dołączenie. |
[TRUST_ERROR] | Konfiguracja zaufania lub własny podpis artefaktu (kwestia, nie miejsce tworzenia definicji) | Nieczytelna polityka zaufania lub przypięty korzeń zaufania; polityka bezkluczowa niedeklarująca żadnej zaufanej tożsamości; polityka podpisywania wymagająca podpisu dla publikowanego rodzaju; zarejestrowana bramka dołączenia werdyktu, której konfiguracja już nie dołącza. Albo: podpis, który nie przechodzi weryfikacji; artefakt bez podpisu tam, gdzie jest on wymagany; niezaufany podpisujący; plugin, którego zarejestrowana zaufana tożsamość już się nie zgadza. Poprawka: poprawić konfigurację lub zatwierdzony rekord zaufania albo podjąć decyzję co do artefaktu — krótki kod wskazuje, które z nich. |
Prefiksy kontekstu poszczególnych providerów (helm: node "<id>": ..., compose: node "<id>": ...) pojawiają się w części komunikatu wyników [TRANSLATION_ERROR] i [CATALOG_ERROR], aby wskazać zawodzącego providera, gdy w grę wchodzi więcej niż jeden provider.
Błędy natywne bibliotek
Błędy, które powstają wewnątrz bazowej biblioteki (błędy ładowania chartów Helm SDK, błędy parsera YAML docker-compose, błędy wejścia/wyjścia plików wynikające z brakującej ścieżki źródłowej), są opakowywane prefiksem kontekstu danego dostawcy i zgłaszane pod [TRANSLATION_ERROR] lub [CATALOG_ERROR], zależnie od tego, czy wystąpiły podczas syntezy, czy podczas ładowania zawartości katalogu. Opakowany komunikat biblioteki zachowuje dosłownie oryginalną diagnostykę narzędzia, dzięki czemu autorzy mogą odszukać ją w dokumentacji samego narzędzia.
Odsyłacze
fatal-halts.md— katalog wszystkich błędów krytycznych przerywających kompilację, z zamierzonym komunikatem i sposobem naprawy dla każdego z nich.warnings.md— niekrytyczne ostrzeżenia emitowane przez kompilator.vocabulary/validation-surface.md— cztery warstwy walidacji schematów i wzajemne oddziaływanie kształtów ich błędów.