Nguyên tắc diễn giải lỗi
Pipeline biên dịch của Aggrega phát ra lỗi từ nhiều nguồn — các trình xác thực schema, bộ phân giải (resolver), bộ dựng IR, các provider, engine template của Go, và các thư viện YAML / Helm / docker-compose nền tảng mà các provider bao bọc. Các lỗi được đẩy lên CLI mở đầu bằng một phần đầu trong ngoặc vuông nêu tối đa hai thứ — một danh mục, cho biết mối quan tâm nào cần xem xét (với hầu hết các giá trị, đó là bề mặt soạn thảo gây lỗi), và mã ngắn của điều kiện đã dừng quá trình build — theo sau là một con trỏ tới nguồn và một thông điệp. Khi một plugin phát sinh điều kiện đó, mã được định danh kèm theo plugin đã phát sinh nó, vì nhiều plugin có thể báo cáo cùng một điều kiện. Trang này mô tả cấu trúc của đầu ra đó để người soạn thảo có thể trực tiếp diễn giải các thông điệp lỗi.
Để xem danh mục theo từng lỗi (mọi điểm dừng nghiêm trọng kèm hướng dẫn khắc phục), xem fatal-halts.md. Để tìm hiểu bốn lớp xác thực schema và cách các dạng lỗi của chúng tương tác với nhau, xem vocabulary/validation-surface.md.
Các loại lỗi
Thẻ loại lỗi cho biết bạn cần xem xét mối quan tâm nào. Phần lớn các thẻ nêu tên bề mặt soạn thảo nơi cần sửa; số còn lại nêu một mối quan tâm không phải là lỗi soạn thảo của ai cả — việc lấy một artifact, một phán quyết quản trị, hoặc tin cậy và ký số — và trong mọi trường hợp, mã ngắn đứng cạnh loại lỗi trong phần đầu là thứ xác định điều kiện cụ thể:
[DEVELOPER_ERROR]— lỗi gắn với việc soạn thảo Aggregate. Chỗ cần sửa nằm trong YAML của Aggregate hoặc trong phần catalog do nhà phát triển soạn (giá trị của Component, các socketuses, các gắn kết Feature). Ví dụ về bề mặt: resolver dừng vì các vấn đề phía Aggregate; vi phạm selector vàappliesTotrên những gì Aggregate đã viết.[OPS_ERROR]— lỗi gắn với chính các tài liệu của người vận hành, tức Release và Manifest. Chỗ cần sửa nằm trong YAML của Release (cấu trúc liên kết ranh giới, giá trị tham số, các gắn kết Feature ở cấp Release) hoặc trong YAML của Manifest (một kiểu được triển khai qua Recipe nào, và các ràng buộc annotation viết cạnh nó). Ví dụ về bề mặt: xác thực schema của Release; đánh giá template đường dẫn ranh giới; xung độtsubDirectorygiữa các provider; Manifest từ chối ánh xạ và ràng buộc annotation; một quy tắc từ chối một kết nối mà Release nối, hoặc một gắn kết mà nó điền trên một kết nối — selector của một socket, selector của một slot, một slot mà socket khai báo là bắt buộc; một quy tắc từ chối một Feature mà chỉ Release gắn, vào một component hoặc vào một ranh giới —appliesTocủa Feature, selector của một slot, schema đã khai báo của nó.[CATALOG_ERROR]— lỗi gắn với một thực thể catalog (Recipe, FeatureRecipe, Component, Feature, Plugin). Chỗ cần sửa nằm trong nội dung catalog. Ví dụ về bề mặt: các quy tắc về hình dạng Recipe; kiểm tra chéofeaturesSchemacủa Workload; lỗi phân tích template trong các template do catalog soạn.[TRANSLATION_ERROR]— lỗi gắn với bước tổng hợp phía provider (một plugin provider cố gắng chuyển một Workload, đầu ra valuesMapping hoặc một overlay có nguồn thành các artifact gốc của provider). Chỗ cần sửa thường nằm ở hình dạngservices/containers/volumescủa Workload, đầu ra templatevaluesMappingcủa Recipe, hoặc cấu trúc overlay ở chế độ source.[FETCH_ERROR]— lỗi gắn với việc lấy một phụ thuộc đã ghim từ registry hoặc nguồn từ xa, không gắn với bề mặt soạn thảo nào. Cách sửa thường mang tính vận hành: xác thực với registry (docker login <registry>), khôi phục kết nối, hoặc ghim lại một artifact đã bị trôi phiên bản hay bị can thiệp (aggrega pull --upgrade --release <release>). Ví dụ về bề mặt: không tìm thấy một thực thể catalog hoặc chart trên registry; cần xác thực hoặc xác thực thất bại; không truy cập được mạng; digest của một artifact trong bộ nhớ đệm không khớp với lockfile. Lỗi fetch mang theo chỉ dẫn khắc phục cụ thể trong thông báo.[POLICY_ERROR]— bản build bị từ chối bởi một plugin chính sách được gắn ở vai trò phán quyết quản trị. Đây không phải lỗi ở bề mặt soạn thảo: đầu vào hợp lệ về hình thức, nhưng không đạt một quy tắc quản trị (tuân thủ, FinOps hoặc bảo mật) mà plugin thực thi. Cách sửa là đưa những gì bạn đã soạn về tuân thủ chính sách được thực thi, hoặc xem xét lại việc gắn chính sách. Thông báo nêu tên plugin từ chối và mang theo thông điệp quy tắc mà nó cung cấp.[TRUST_ERROR]— lớp tin cậy và ký số đã từ chối thao tác. Loại lỗi này nêu một mối quan tâm chứ không phải một bề mặt soạn thảo, và nó bao gồm hai cách khắc phục mà bạn có thể phân biệt nhờ mã ngắn bên cạnh. Cấu hình tin cậy của bạn sai: một chính sách tin cậy không đọc được, một trust root đã ghim không tải được, một chính sách keyless không khai báo danh tính tin cậy nào, một chính sách ký yêu cầu chữ ký cho loại artifact bạn đang phát hành, hoặc một plugin được ghi nhận là tin cậy cho một gắn kết phán quyết mà cấu hình của bạn không còn gắn nữa. Artifact này không qua được xác minh: một chữ ký không xác minh được với trust anchor, một artifact không mang chữ ký ở nơi cần có, một chữ ký từ một người ký có thật nhưng không được tin cậy, hoặc một plugin mà danh tính tin cậy đã ghi nhận không còn khớp với những gì được phân giải. Trong trường hợp thứ nhất, chỗ cần sửa nằm trong cấu hình của bạn hoặc trong bản ghi tin cậy đã commit; trong trường hợp thứ hai, đó là một quyết định về artifact — khôi phục bản đã được xem xét, hoặc xem xét và ghi nhận lại những gì đã thay đổi.
Một phát hiện về gắn kết Feature đi theo tài liệu đã viết ra nó
Một Feature có thể được gắn ở cả hai tài liệu — Aggregate gắn nó trên một component hoặc trên một subsystem, Release gắn trên mục của nó cho một component hoặc trên một ranh giới — vì vậy loại của một phát hiện về gắn kết được xác định từ nơi gắn kết được viết, chứ không phải từ component mà nó chạm tới. Phát hiện được định vị tại mục features: đã viết gắn kết đó, trong tài liệu đó, và được quy cho tác giả của tài liệu đó: một gắn kết chỉ Release tạo ra được báo cáo tại đường dẫn riêng của Release dưới dạng [OPS_ERROR], còn gắn kết do Aggregate tạo ra được báo cáo tại đường dẫn của Aggregate dưới dạng [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.Khi cả hai tài liệu cùng viết một gắn kết — Aggregate nêu tên Feature của nó, Release định cỡ nó — một phát hiện về toàn bộ gắn kết được định vị tại nơi Feature của nó được nêu tên, tức là Aggregate. Một phát hiện về một phần cấu hình của nó được định vị tại nơi phần đó được viết: values của nó thuộc về nhà phát triển, trong Aggregate, còn infra thuộc về người vận hành, trong Release. Một gắn kết do việc mở rộng theo annotation tạo ra không được viết bởi mục features: nào, nên phát hiện về nó được định vị tại component, trong tài liệu khai báo component đó, dưới dạng [DEVELOPER_ERROR].
Một slot bắt buộc bị bỏ trống là trường hợp duy nhất không tài liệu nào viết ra. Không có gắn kết nào để trỏ tới, nên phát hiện nằm tại component trong Aggregate và được ghi nhận là [DEVELOPER_ERROR], và cách khắc phục của nó nêu cả hai tài liệu, vì tài liệu nào cũng có thể điền slot: “Attach a Feature at that name, in the Aggregate or in the Release, on the component or at a scope above it. (Hãy gắn một Feature tại tên đó, trong Aggregate hoặc trong Release, trên component hoặc ở một phạm vi phía trên nó.)”
Trình soạn thảo đọc cùng cách định vị đó: một phát hiện được định vị trong Release được hiển thị trên tài liệu của Release, tại khóa đã viết ra nó, và hoàn toàn không hiển thị trên tài liệu của Aggregate; một phát hiện được định vị trong tài liệu của một module mà Aggregate import được hiển thị trên tài liệu của module đó theo cùng cách.
Hình dạng đầu ra
Một chẩn đoán được in ra mở đầu bằng phần đầu trong ngoặc vuông và con trỏ nguồn, rồi đặt thông điệp trên một dòng thụt lề riêng:
[CATEGORY SHORTCODE] <source> <message>Phần đầu mang hai token, và chúng trả lời những câu hỏi khác nhau. Danh mục là một trong các danh mục ở trên và cho biết cần xem xét mối quan tâm nào. Mã ngắn là chữ E và bốn chữ số, và nó gọi tên chính xác điều kiện đã dừng bản dựng: hãy trích dẫn nó trong báo cáo, gõ nó vào ô tìm kiếm, hoặc tra nó trong bảng liệt kê mọi điều kiện trong sentinels.md. Không token nào suy ra được từ token kia, đó là lý do cả hai đều được in — và khi một danh mục bao gồm nhiều hơn một cách khắc phục, như [TRUST_ERROR], thì mã ngắn là thứ cho bạn biết mình đã gặp trường hợp nào.
Mã do một plugin phát sinh được định danh bằng chính plugin đã phát sinh nó
Mỗi mã ngắn chỉ một điều kiện mà Aggrega khai báo, và không có hai điều kiện nào dùng chung một mã: một điều kiện được khai báo dưới một số mà điều kiện khác đã giữ sẽ bị từ chối trước khi trình biên dịch đọc bất kỳ đầu vào nào. Plugin không tự cấp phát mã. Khi báo cáo một lỗi, plugin nêu một trong các điều kiện mà Aggrega khai báo — một trong vài điều kiện chung mô tả cách một plugin thất bại, hoặc một điều kiện cụ thể hơn nếu phù hợp — và cung cấp câu nói rõ điều gì thực sự đã xảy ra. Vì vậy hai plugin có thể báo cáo cùng một mã ngắn, và khi đó chúng đang báo cáo cùng một điều kiện.
Điều mà mã không thể cho biết là plugin nào đã gặp điều kiện đó, và một phần đầu báo cáo điều kiện do plugin phát sinh sẽ mang danh tính của plugin ngay trước mã:
[CATEGORY PLUGIN/SHORTCODE] <source> <message>Mã ngắn luôn là đoạn cuối cùng — chữ E và bốn chữ số, sau dấu / cuối cùng. Danh tính của một plugin mang các dấu phân cách riêng của nó, và có thể mang một phiên bản, nên việc đọc từ cuối thay vì từ dấu / đầu tiên là điều giúp lấy lại được mã từ bất kỳ phần đầu nào. Mọi thứ trước đoạn cuối cùng đó là plugin.
Đoạn cuối được tra như mọi mã ngắn khác, bất kể plugin nào đã phát sinh nó: bảng liệt kê mọi điều kiện trong sentinels.md có liệt kê nó, và aggrega explain tra được nó. Hãy chỉ trích dẫn đoạn cuối — phần định danh cho biết plugin nào đã gặp điều kiện, chứ không cho biết đó là điều kiện nào. Một plugin nêu một mã mà Aggrega không khai báo — một số không điều kiện nào giữ, hoặc một số đã ngừng dùng — sẽ không được in mã đó: build dừng với E0293, được định danh kèm plugin đó, và thông điệp của nó trích dẫn mã mà plugin đưa ra, nêu các điều kiện chung đó, và giữ nguyên câu của chính plugin.
Một phần đầu in mã ngắn trần là đang báo cáo điều kiện do chính Aggrega phát sinh, bao gồm cả trường hợp một plugin thất bại mà không nêu điều kiện riêng nào. Khi đó điều kiện lỗi plugin chung của trình biên dịch là thứ đã dừng bản dựng, và thông điệp của plugin mang chi tiết.
Token nào cũng có thể vắng mặt, và token vắng mặt sẽ bị lược bỏ
Không có gì thay thế cho một token mà chẩn đoán không có — không placeholder, không ngoặc vuông rỗng. Có ba cách để phần đầu bị rút ngắn, và mỗi cách cho bạn biết một điều:
- Không có mã ngắn. Lỗi không nêu điều kiện riêng nào của Aggrega — thường nhất là một lỗi do thư viện mà trình biên dịch bao bọc báo cáo. Phần đầu chỉ in danh mục, nên bạn vẫn biết cần xem bề mặt nào.
- Không có danh mục. Lỗi không có mối quan tâm nào để hướng bạn tới, nên không có danh mục nào được đoán. Phần đầu chỉ in mã ngắn, và mã là thứ bạn cần tra. Hai tình huống tạo ra điều này, và chúng đọc giống nhau vì với mục đích của bạn chúng giống nhau — không tình huống nào cho bạn biết cần xem ở đâu, và mã cho bạn biết chuyện gì đã xảy ra. Một là lỗi trong chính trình biên dịch, khi thông điệp nói rõ như vậy và yêu cầu bạn báo cáo; trường hợp thực sự xảy ra là các góc nhìn riêng của trình biên dịch về catalog mâu thuẫn với nhau. Hai là một lỗi có nêu điều kiện nhưng chưa từng đi qua bề mặt nào xếp nó vào một mối quan tâm, đây là hình dạng thường gặp của một sự từ chối phát sinh ở ranh giới lệnh. Danh mục không bao giờ được bịa ra để lấp chỗ trống, và đó là mục đích của việc lược bỏ chứ không phải hạn chế của nó: danh mục trả lời câu hỏi “tôi cần xem mối quan tâm nào”, và một câu trả lời được đưa ra khi câu hỏi không có câu trả lời thì không phải là câu trả lời thận trọng mà là câu trả lời sai, và sẽ được hành động theo trước tiên. Cũng nên nói rằng suy luận ngược lại không đúng: một phần đầu có mang danh mục không phải lúc nào cũng chỉ vào thứ bạn đã viết, vì
[FETCH_ERROR],[POLICY_ERROR]và[TRUST_ERROR]mỗi cái gọi tên một mối quan tâm chứ không phải một bề mặt soạn thảo. - Không có cả hai. Ngoặc vuông bị lược bỏ hoàn toàn và chẩn đoán chính là thông điệp của nó. Đây là lỗi không nêu điều kiện riêng nào của Aggrega và không có mối quan tâm nào để hướng bạn tới: một lệnh từ chối đối số của nó, một tệp nó không đọc được, một sự hủy bỏ, hoặc một lỗi do thư viện mà trình biên dịch bao bọc báo cáo mà không có điều kiện nào của chúng tôi bên dưới. Không có gì để tra trong
sentinels.md, và thông điệp là toàn bộ những gì lỗi muốn nói.
Cùng lỗi đó rút gọn thành một dòng, dạng phù hợp cho đầu ra log hơn là cho terminal, mang danh mục và bỏ mã ngắn:
[CATEGORY] <source>: <message>Danh mục vắng mặt ở phần đầu thì cũng vắng mặt ở đây, kể cả ngoặc vuông, nên dòng này không bao giờ là [] <source>: <message>. Dạng một dòng được bao lại vào các khung bao ngoài khi lỗi truyền lên, nên một thẻ rỗng sẽ bị mang vào từng khung đó.
Nguồn là một con trỏ có cấu trúc — thường là <file>:<line>:<column> khi có vị trí YAML, hoặc một định danh logic (tên thực thể catalog, tên Release, đường dẫn ranh giới) khi không áp dụng vị trí tệp. Dạng thứ ba, <file> at <key>, xuất hiện khi con trỏ biết cả tài liệu lẫn khóa soạn thảo bên trong nó nhưng không có vị trí byte: tệp là thứ bạn mở, và khóa là thứ cần xem khi đã mở. Thông điệp là chẩn đoán riêng của từng bề mặt.
Một lỗi liên quan đến một instance trong bản build của bạn — một component, một component do module đóng góp, hoặc chính một module — nêu tên instance đó sau vị trí, dưới dạng (instance <name>), nên aggregate.yaml (instance shop) là Aggregate khai báo module shop. Khi lỗi không có tài liệu nào để trỏ tới, instance đứng riêng dưới dạng instance <name>: một nhà cung cấp bị lỗi khi đang render component adminer sẽ in [TRANSLATION_ERROR E0082] instance adminer, và các dòng bên dưới mang phần còn lại của lỗi, bao gồm mọi tài liệu mà lỗi nêu tên. Tên đó là tên mà Aggregate dùng để khai báo component; một component do module đóng góp được đặt tên theo đường dẫn của nó qua module, chẳng hạn shop.cart. Một instance không bao giờ được in ở chỗ dành cho một tệp, nên bất cứ thứ gì mở đầu nguồn đều là một tài liệu bạn có thể mở, hoặc một trong các định danh logic ở trên.
Một quy tắc được đánh giá trên đồ thị hoàn chỉnh báo cáo theo dạng thứ ba đó, và khóa là thứ phân biệt hai phát hiện khi chỉ thông điệp thì không thể. Một quy tắc loại này gọi tên kiểu component khai báo chứ không phải thực thể, nên hai component cùng một kiểu vi phạm cùng quy tắc sẽ mang cùng thông điệp về cùng tệp:
[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")Khóa là phần duy nhất khác nhau, và nó là thứ chỉ ra cần sửa component nào trong hai component. Cả hai phát hiện mang cùng mã ngắn vì cả hai là cùng một điều kiện, gặp hai lần — mã ngắn gọi tên quy tắc, còn khóa gọi tên lần xuất hiện.
Hai dòng nữa thuộc về hình dạng này, dành cho lỗi mang ngữ cảnh để điền vào chúng — biểu thức template đã thất bại, và ảnh chụp các pillar trong phạm vi tại nơi nó thất bại:
[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>Dòng expression: mang đoạn trích template đã gây ra lỗi. Khối active pillars: liệt kê các khóa pillar cấp cao nhất có sẵn tại điểm lỗi, để tác giả thấy được những gì có thể truy vấn. Cả hai bị lược bỏ khi lỗi không mang thông tin nào trong số đó.
Các khung ngữ cảnh lồng nhau
Một lỗi thường đi qua nhiều hơn một bề mặt trên đường tới CLI: một giai đoạn tải bao bọc lỗi cụ thể của thực thể, và lỗi đó lại bao bọc một sentinel giải thích quy tắc. Mọi khung đã được phân loại trong một chuỗi như vậy đều được hiển thị — khung ngoài cùng là phần đầu theo dạng ở trên, mỗi khung lồng bên trong là một dòng tiếp nối caused by: thụt lề, mang thẻ danh mục, con trỏ nguồn và thông điệp riêng của nó. Khung trong cùng có trỏ tới tệp luôn hiển thị:
[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")Chỉ phần đầu mang mã ngắn, còn các dòng tiếp nối chỉ mang danh mục của chúng. Điều kiện được nêu tên một lần, tại nơi người đọc gặp lỗi; các khung bên dưới một dấu caused by: là chính lỗi đó nhìn từ sâu hơn bên trong, nên lặp lại định danh của nó trên mỗi khung sẽ chỉ thêm dòng mà không thêm thông tin. Một khối note: không phải là dòng tiếp nối và không theo quy tắc này — nó báo cáo các điều kiện của những tài liệu khác chứ không phải cùng một điều kiện nhìn từ sâu hơn; phần bên dưới trình bày về nó. Mã mà phần đầu in ra là mã mà chuỗi nêu tên — ở đây là quy tắc ở tận cùng — nên một khung ngữ cảnh giai đoạn ở trên cùng vẫn xác định được điều kiện bên dưới nó.
Đọc từ trên xuống: giai đoạn bị lỗi, rồi đến thực thể (cùng đường dẫn tệp của nó) đã gây ra lỗi, rồi đến quy tắc mà nó vi phạm. Một khung lồng nhau không thêm gì so với khung cha (cùng danh mục, cùng nguồn, thông điệp mà khung cha đã chứa) sẽ được loại trùng thay vì lặp lại, và một lời giải thích cuối chỉ được hiển thị khi các khung phía trên chưa mang nội dung của nó.
Một chuỗi sẽ sâu hơn mỗi khi lỗi đi qua nhiều bề mặt hơn trên đường ra, và quy tắc vẫn áp dụng ở mọi độ sâu. Một template bị từ chối bên trong Workload được tổng hợp của một Recipe đi qua ba bề mặt — nút đang được render, bề mặt template của Recipe, và chính template đó:
[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)Hãy đọc từ trên xuống như trước, và lưu ý ba điều mà độ sâu thêm vào làm lộ ra. Mã ngắn xuất hiện một lần, ở phần đầu, dù có bao nhiêu dòng tiếp nối theo sau. Khung trong cùng là nơi chứa câu riêng của điều kiện, nên dòng sâu nhất vừa là dòng để đối chiếu vừa là dòng cho biết cần thay đổi gì. Và một khung không có con trỏ nguồn chỉ in danh mục của nó: khung ở giữa phía trên nêu tên bề mặt mà nó gặp lỗi ngay trong thông điệp, vì bề mặt đó là một template chứ không phải một tệp và không có vị trí để trỏ tới.
Khi lỗi rẽ nhánh bên dưới một khung — một giai đoạn đã thu thập nhiều vi phạm độc lập trước khi dừng — dòng tiếp nối mang một số đếm, và mọi lỗi đã thu thập được hiển thị bên dưới nó, ngăn cách bởi cùng đường kẻ --- mà các chuỗi đa lỗi bên dưới sử dụng:
[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 itCác lỗi đã thu thập bên dưới số đếm cũng là dòng tiếp nối, nên không lỗi nào lặp lại mã ngắn của phần đầu — đó là điều giúp một nhánh gồm hàng chục vi phạm không in cùng một định danh hàng chục lần.
Một ngữ pháp phân cách duy nhất áp dụng xuyên suốt: --- giữa các lỗi ngang hàng, caused by: giữa các khung ngữ cảnh lồng nhau.
Một tệp catalog bị từ chối và lỗi mà nó giải thích
Việc nạp một catalog để phân giải những gì một Release phụ thuộc vào được thiết kế có chủ ý để chấp nhận lỗi: một tệp không thể đọc, hoặc một tài liệu Aggrega không thể phân tích cú pháp hoặc lập chỉ mục, sẽ bị từ chối và ghi nhận lại thay vì làm hủy toàn bộ quá trình nạp. Chính điều đó giúp một thực thể bị hỏng mà Release của bạn không bao giờ chạm tới không làm hỏng một bản build không liên quan.
Hệ quả là một tệp bị từ chối sẽ lặng lẽ biến mất khỏi catalog — và nếu Release của bạn thực sự chạm tới nó, thứ thất bại là nỗ lực phân giải một tham chiếu tới những gì tệp đó đã khai báo. Lỗi đó là hệ quả của việc từ chối chứ không phải bản thân việc từ chối, vì vậy báo cáo sắp xếp hai thứ theo thứ tự nhân quả ở bất cứ đâu nó có thể chỉ đích danh việc từ chối:
[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"Việc từ chối đứng đầu, với category và mã ngắn của riêng nó, vì nó chỉ ra thứ bạn có thể xử lý: cách sửa là một implements: bị thiếu trong một Recipe, chứ không phải điều gì liên quan đến cách một tham chiếu được tra cứu trong registry. Lỗi phân giải vẫn được báo cáo, bên dưới nó, vì đó là thứ cho biết tại sao tài liệu đó lại cần thiết.
Một việc từ chối chỉ đứng đầu khi có đúng một tệp bị từ chối khai báo danh tính mà tham chiếu thất bại chỉ tới. Việc so khớp dựa trên danh tính mà mỗi tài liệu tự khai báo — kind, tên, phiên bản của nó, và với một recipe là spec.capability giới hạn phạm vi của nó — vì vậy một tệp bị từ chối khai báo đúng thứ tham chiếu yêu cầu chính là tệp mà tham chiếu đó lẽ ra đã được phân giải tới. Từ đó có hai hệ quả. Một tham chiếu nêu một khoảng phiên bản thay vì một phiên bản không chỉ tới tài liệu đơn lẻ nào, nên nó không chỉ ra được gì. Và một tài liệu hỏng đến mức không đọc được header thì không khai báo danh tính nào cả, nên nó không bao giờ bị nêu là nguyên nhân của bất cứ điều gì.
Khi không có tệp bị từ chối nào khai báo danh tính đó, hoặc có nhiều hơn một tệp, báo cáo sẽ giống như khi không có bản ghi từ chối nào: lỗi đứng đầu, và mọi việc từ chối được liệt kê bên dưới để bạn cân nhắc. Nêu sai tệp làm nguyên nhân còn tệ hơn không nêu tệp nào, vì bạn sẽ hành động dựa trên nó.
[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 schemaCó vài điều về dạng thứ hai đó đáng biết, vì mỗi điều trả lời một câu hỏi mà khối thông báo nếu không sẽ đặt ra.
Phần đầu nêu lỗi, không phải một việc từ chối. Mã ngắn ở trên cùng là mã mà lỗi phân giải đã đưa ra, vì lỗi đó là thứ dẫn đến đây — không có tệp bị từ chối nào được chỉ ra, nên không tệp nào đứng đầu dòng. Nó không kèm category bên cạnh vì không có gì trên đường đi này xếp lỗi vào một mối quan tâm nào. Phần đầu riêng của mỗi việc từ chối nằm trên mục riêng của nó bên dưới, và đó là nơi bạn đọc nó.
Mọi việc từ chối đều được liệt kê, không chỉ việc có liên quan. Đi đến dạng này nghĩa là bản ghi không thể chỉ ra một việc duy nhất, nên ghi chú nêu rõ sự phân biệt thay vì phỏng đoán: một việc từ chối nằm ngoài closure của Release này được chấp nhận và không thể là thứ đã thất bại, nên việc từ chối chỉ tới thứ mà Release chạm tới là mục duy nhất giải thích được lỗi. Hãy đối chiếu các mục với những gì Release của bạn thực sự sử dụng.
Mỗi mục mang phần đầu trong ngoặc vuông của riêng nó — category và mã ngắn của riêng nó. Đây là nơi duy nhất một mã ngắn xuất hiện bên dưới phần đầu của chẩn đoán, và đó không phải là ngoại lệ của quy tắc về phần tiếp nối ở trên mà là hệ quả của nó: một mục dưới note: không phải cùng một lỗi nhìn từ sâu hơn, mà là một điều kiện khác do một tài liệu khác đưa ra. Việc nêu điều kiện của nó cho phép bạn tra cứu việc từ chối và sửa tệp, đó chính là hành động mà khối này tồn tại để hỗ trợ.
Một tệp bị từ chối có phần header hỏng tới mức không thể khôi phục danh tính mà nó khai báo sẽ chỉ được liệt kê theo đường dẫn. Đó là cách đọc trung thực về một tài liệu mà không gì có thể xem được bên trong, và đường dẫn vẫn đủ để mở tệp. Một tệp hỏng tới mức ngay cả kind của nó cũng không đọc được — chẳng hạn một tệp không phân tích được dưới dạng YAML — được liệt kê theo cách này khi nó khai báo một apiVersion của Aggrega, bằng một dòng bắt đầu, không thụt lề, với apiVersion: và một giá trị bắt đầu bằng aggrega.ai/, kèm theo lý do của chính trình phân tích cú pháp: dòng đó, và điều mà trình phân tích cú pháp mong đợi ở đó. Một tệp YAML khai báo apiVersion khác, hoặc không khai báo gì, không phải là tài liệu Aggrega — chẳng hạn template của một chart, hoặc một tệp cấu hình được giữ bên cạnh các thực thể — nên nó không bao giờ được liệt kê, dù hỏng đến đâu.
Một tệp khai báo một loại mà không catalog nào chứa chỉ được nêu tên ở nơi nó giải thích lỗi. Một tài liệu khai báo một apiVersion Aggrega và một kind mà không catalog nào chứa — chẳng hạn Componnent viết sai chính tả — bị mọi lần tải bỏ qua, nên nó không phải là một lần từ chối và không được liệt kê trong số các lần từ chối. Khi tham chiếu thất bại yêu cầu đúng tên mà tệp đó khai báo, và đúng phiên bản nếu tham chiếu có nêu phiên bản, báo cáo sẽ nêu tên tệp đó trong một ghi chú riêng bên dưới lỗi, bất kể tham chiếu được thu thập dưới loại nào — trên mọi bề mặt được liệt kê dưới đây, và trên aggrega build dù nó đọc một lockfile có sẵn hay điền một lockfile trước:
[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 directoriesLỗi vẫn đứng đầu: loại mà tệp khai báo không xác định danh tính nào, nên tệp không bao giờ được chọn riêng làm lần từ chối mở đầu báo cáo. Phần giải thích về nơi các thực thể cục bộ được đọc bị lược khỏi báo cáo đó, vì tệp đã nằm ở nơi catalog đọc và việc di chuyển nó sẽ không giúp ích gì. Một tệp thuộc loại mà không catalog nào chứa nhưng khai báo một tên khác thì không giải thích gì về lỗi này và không được nhắc đến. aggrega serve, có các thông báo chỉ một dòng, mang cùng ghi chú đó trên dòng ấy — note: a catalog file declares the name this reference asks for under a kind a catalog does not hold, so the load skipped it: theo sau là lần từ chối của tệp — và không bao giờ liệt kê một tệp như vậy trong số các tệp bị bỏ qua khi tải; công cụ describe của aggrega mcp, khi được hỏi về một tên theo các điều kiện của một Release, cũng nêu tên tệp đó thay cho phần giải thích ấy. aggrega validate và aggrega lint trên toàn catalog báo cáo mọi tệp như vậy dù có thứ gì chạm tới nó hay không — xem fatal-halts.md §“A catalog document declares a kind a catalog does not hold (Một tài liệu catalog khai báo một loại mà catalog không chứa)”.
Dù bạn nhận được dạng nào, lỗi vẫn giữ danh tính riêng của nó. Ghi chú được thêm vào lỗi chứ không hiển thị đè lên nó, và việc đặt một việc từ chối lên đầu chỉ thay đổi thứ bạn đọc trước — nên điều kiện mà lỗi đưa ra vẫn nguyên vẹn trong cả hai trường hợp: mã ngắn của nó vẫn phân giải được, và một công cụ so khớp theo điều kiện vẫn khớp.
Khi chính tài liệu bị từ chối là thứ một lệnh báo cáo, việc từ chối được nêu một lần. aggrega inspect <name> nạp catalog một cách nghiêm ngặt, nên một tài liệu bị quá trình nạp từ chối sẽ làm nó dừng lại, và những gì nó in ra là việc từ chối tài liệu đó dưới dạng một chẩn đoán duy nhất: phần đầu mang category và mã ngắn của việc từ chối, tài liệu là nguồn của nó, và bên dưới là những gì sai trong tài liệu — với vi phạm schema là các khóa bị vi phạm cùng dòng và cột của chúng, và lời khuyên. Quá trình nạp đưa ra lỗi đã đi qua thư mục nó đang duyệt và bước đọc tệp, và những thứ đó không được in thành các frame riêng, vì mỗi frame sẽ lại nêu cùng tài liệu đó mà không thêm thông tin nào. aggrega serve, khi được hỏi một tên tham chiếu tới gì trong khi một tài liệu bị từ chối khai báo tên đó, sẽ trả lời bằng cùng việc từ chối đó với cùng câu chữ trên một dòng, kèm theo ghi chú rằng tệp đã bị bỏ qua khi nạp. Như ở trên, điều kiện của việc từ chối vẫn so khớp được trong cả hai trường hợp.
Cả hai dạng đều đến với bạn ở bất cứ nơi nào việc phân giải đó chạy. aggrega build, aggrega pull, aggrega validate --release và aggrega inspect --closure tạo ra chúng tại terminal, aggrega validate trên một Recipe có đích implements không được tìm thấy cũng vậy, và một trợ lý AI được kết nối qua aggrega mcp nhận cùng thông tin đó từ các công cụ build và validate, cùng với lời từ chối đứng đầu trên một dòng từ một lần đọc catalog:// đối với một thực thể mà một tệp bị từ chối khai báo. Việc bạn hỏi từ bề mặt nào không thay đổi gì về tệp nào bạn được chỉ tới để mở — một bên gọi truy cập aggrega mcp qua HTTP được cho biết tệp đó theo đường dẫn tương đối với thư mục gốc workspace, và không được cho biết một tệp nằm ngoài workspace mà máy chủ đó phục vụ — và khi một việc từ chối đứng đầu, hợp đồng soạn thảo mà câu trả lời chỉ tới là hợp đồng dành cho kind mà tài liệu bị từ chối đó khai báo — không phải kind của tham chiếu đã thất bại.
Lớp lỗi vỏ tài liệu
Mọi tài liệu thực thể — các thực thể catalog, Aggregates, Manifests, Releases — đều được kiểm tra theo JSON schema đã công bố của loại của nó khi được nạp, trước bước phân tích có kiểu. Một tài liệu vi phạm vỏ của nó (một khóa không xác định, một trường bắt buộc bị thiếu, một giá trị sai hình dạng, một cấu trúc bị cấm như Release values:) sẽ dừng lại rõ ràng với một chẩn đoán nêu điều kiện trước tiên, sau đó là loại thực thể và tệp, rồi từng khóa hoặc hình dạng vi phạm cùng dòng và cột nơi nó nằm, và cuối cùng là cách xử lý:
[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 schemaChẩn đoán mở đầu bằng điều kiện, nêu loại và tệp, và kết thúc bằng việc cần làm; mỗi vi phạm ở giữa chỉ mang line:column, vì phần đầu đã nêu tệp. Mỗi khóa vi phạm được báo cáo tại vị trí riêng của nó thay vì tại vị trí của khối chứa nó, nên dòng và cột trỏ vào đúng khóa bạn cần thay đổi. Khi hình dạng của vị trí đến từ một định nghĩa tái sử dụng trong schema, chẩn đoán nêu định nghĩa đó sau từ against — against /$defs/boundary ở trên — để rõ khóa đã được đối chiếu với hợp đồng nào, và định nghĩa không bị đọc như thêm một bước trên đường dẫn khóa bạn đã viết. Một tài liệu có nhiều vi phạm liệt kê từng vi phạm tại vị trí riêng của nó, theo thứ tự khóa, và báo cáo dừng sau bốn vi phạm kèm số lượng các vi phạm còn lại.
Có hai điều đáng biết về nơi một vị trí trỏ tới, vì cả hai đều hữu ích chứ không gây bất ngờ:
- Một khóa bắt buộc bị thiếu không có vị trí riêng — theo định nghĩa, nó không có trong tài liệu. Thay vào đó, vi phạm trỏ vào khóa bao quanh, là nơi mục bị thiếu thuộc về. Vì vậy
spec.capability: missing required propertytrỏ vàospec:, và đó là nơi bạn thêm nó. - Một khóa mà chính tên của nó chứa dấu chấm — mọi nhãn
component.aggrega.ai/…và chú thíchfeatures.aggrega.ai/…— được báo cáo tại khối chứa nó thay vì tại chính mục đó, vì các dấu chấm được đọc như các bước đi sâu vào tài liệu. Một vi phạm trên một nhãn trỏ vàolabels:.
Khi một vi phạm nêu một khóa hoàn toàn không có trong tài liệu — chẳng hạn bỏ sót cả một khối metadata: — vị trí được lược bỏ thay vì phỏng đoán, và vi phạm chỉ gồm đường dẫn khóa và thông điệp. Một vị trí mà bạn phải nghi ngờ còn tệ hơn không có vị trí nào.
Danh mục đi theo bề mặt soạn thảo: [CATALOG_ERROR] cho các thực thể catalog, [DEVELOPER_ERROR] cho Aggregates, [OPS_ERROR] cho Releases và Manifests. Cùng một cổng kiểm tra chạy ở mọi bề mặt nạp thực thể — aggrega build, aggrega lint, aggrega validate, và các chẩn đoán trình soạn thảo mà aggrega serve công bố — nên một khóa thừa hoặc viết sai sẽ bị từ chối ở bất cứ nơi nào tài liệu được đọc lần đầu thay vì bị âm thầm bỏ qua. Mỗi bề mặt đó xác định vị trí theo cùng một cách, nên chúng trỏ vào cùng một khóa, và mỗi bề mặt đọc câu của điều kiện từ chính điều kiện đó: dòng mà trình soạn thảo của bạn gạch chân là dòng mà terminal nêu, và câu mở đầu mục của trình soạn thảo là câu mà terminal mở đầu. Điều hai bề mặt không chia sẻ là toàn bộ thông điệp, và điều đó là có chủ ý — terminal nhóm mọi phát hiện dưới một tiêu đề và kết thúc bằng lời khuyên cho đường dẫn, còn trình soạn thảo phát ra một mục cho mỗi phát hiện, đặt tại khóa riêng của nó, không lặp lại tệp mà nó đã gắn vào cũng như lời khuyên mà nếu không sẽ phải nói một lần cho mỗi gạch chân. Vì vậy phần hội tụ chính là phần giúp bạn nhận ra điều kiện.
Chuỗi nhiều lỗi
Khi một lần biên dịch phát hiện nhiều vi phạm độc lập (thường gặp nhất là trong quá trình phân tích tĩnh, nơi mọi vi phạm về selector và appliesTo đều được thu thập trước khi bất kỳ vi phạm nào dừng bản dựng), các lỗi được nối thành một chuỗi duy nhất. CLI duyệt chuỗi này và hiển thị từng lỗi con một cách độc lập, phân tách bằng một dòng kẻ ngang:
[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.Dấu phân tách --- là ký tự nguyên văn — người đọc và các công cụ phía sau có thể tách theo nó để liệt kê các lỗi đã được nối. Mỗi lỗi con là một thất bại riêng chứ không phải một chi tiết của lỗi bên cạnh, vì vậy mỗi lỗi mang một phần đầu riêng: danh mục riêng và mã ngắn riêng của nó, mỗi thứ ở nơi nó có, như phần về các thành phần vắng mặt mô tả. Hai vi phạm của cùng một quy tắc có cùng một mã ngắn, như ở trên; hai vi phạm của các quy tắc khác nhau có các mã khác nhau.
Đọc một lỗi từ đầu đến cuối
Với hầu hết các ngữ cảnh soạn thảo, tiền tố danh mục cùng với con trỏ nguồn cho biết cần sửa gì:
| Danh mục | Nơi cần sửa | Ví dụ bề mặt |
|---|---|---|
[DEVELOPER_ERROR] | YAML của Aggregate | Vi phạm selector / appliesTo trên những gì Aggregate đã viết; socket uses phía Aggregate không khớp; resolver dừng do phần soạn thảo của nhà phát triển. |
[OPS_ERROR] | YAML của Release / YAML của Manifest | Mẫu đường dẫn boundary tham chiếu trường không được hỗ trợ; subDirectory gây xung đột đường dẫn; resolver dừng do phần soạn thảo Release; một kết nối mà Release nối, hoặc một attachment mà nó điền trên một kết nối, bị quy tắc của socket hoặc của slot từ chối; một Feature chỉ Release gắn vào, cho một component hoặc một boundary, bị quy tắc của Feature hoặc của slot từ chối; một ánh xạ hoặc ràng buộc annotation của Manifest bị từ chối. |
[CATALOG_ERROR] | Recipe / FeatureRecipe / Component / Feature / Plugin | Các quy tắc hình dạng của Recipe; mẫu FeatureRecipe tham chiếu một trường chỉ dành cho từng component với executionScope: boundary; kiểm tra chéo featuresSchema của Workload thất bại. |
[TRANSLATION_ERROR] | Workload / đầu ra valuesMapping / lớp phủ nguồn | Phân giải cổng probe của Helm; xung đột tên service compose giữa các boundary; hai bên đóng góp compose khai báo cùng một tên volume hoặc config cấp cao nhất với nội dung xung đột; tên chart không khớp trên umbrella helm-chart. |
[FETCH_ERROR] | Thu nhận từ registry / nguồn từ xa (vận hành, không phải soạn thảo) | Không tìm thấy artifact trong registry; cần xác thực; không kết nối được mạng; digest trong bộ nhớ đệm không khớp với lockfile. Cách sửa: xác thực, khôi phục kết nối, hoặc aggrega pull --upgrade --release <release>. |
[POLICY_ERROR] | Plugin chính sách (quy tắc quản trị) | Một plugin chính sách gắn ở vai trò phán quyết quản trị đã từ chối bản build đã lắp ráp theo một quy tắc mà nó thực thi. Cách sửa: đáp ứng chính sách được thực thi hoặc xem xét lại việc gắn. |
[TRUST_ERROR] | Cấu hình tin cậy, hoặc chữ ký của chính artifact (một mối quan tâm, không phải bề mặt soạn thảo) | Một chính sách tin cậy hoặc trust root được ghim không đọc được; một chính sách keyless không khai báo danh tính tin cậy nào; một chính sách ký yêu cầu chữ ký cho loại đang được phát hành; một cổng gắn phán quyết đã ghi nhận mà cấu hình không còn gắn nữa. Hoặc: một chữ ký không xác minh được; một artifact không mang chữ ký nào ở nơi cần có; một người ký không được tin cậy; một plugin có danh tính tin cậy đã ghi nhận không còn khớp. Cách sửa: sửa cấu hình hoặc bản ghi tin cậy đã commit, hoặc đưa ra quyết định về artifact — mã ngắn cho biết trường hợp nào. |
Các tiền tố ngữ cảnh theo từng provider (helm: node "<id>": ..., compose: node "<id>": ...) xuất hiện bên trong phần thông điệp của đầu ra [TRANSLATION_ERROR] và [CATALOG_ERROR] để xác định provider gặp lỗi khi có nhiều hơn một provider tham gia.
Lỗi gốc từ thư viện
Các lỗi phát sinh bên trong một thư viện nền tảng (lỗi nạp chart của Helm SDK, lỗi trình phân tích YAML của docker-compose, lỗi I/O tệp do thiếu đường dẫn nguồn) được bao bọc bằng tiền tố ngữ cảnh theo từng provider và xuất hiện dưới [TRANSLATION_ERROR] hoặc [CATALOG_ERROR], tùy theo việc chúng phát sinh trong quá trình tổng hợp hay trong quá trình nạp nội dung catalog. Thông điệp thư viện được bao bọc giữ nguyên văn chẩn đoán của công cụ gốc để tác giả có thể đối chiếu nó với tài liệu của chính công cụ đó.
Tham chiếu chéo
fatal-halts.md— danh mục theo từng lỗi của mọi lần dừng nghiêm trọng, kèm thông báo dự kiến và cách khắc phục.warnings.md— các cảnh báo không nghiêm trọng mà trình biên dịch phát ra.vocabulary/validation-surface.md— bốn lớp xác thực schema và cách các dạng lỗi của chúng tương tác với nhau.