Παρατηρησιμότητα Πρακτόρων: Hooks, Alloy και Grafana

Τα συστήματα πρακτόρων αποτυγχάνουν με περίεργους τρόπους.

Μερικές φορές το μοντέλο είναι το πρόβλημα. Μερικές φορές το εργαλείο είναι το πρόβλημα. Μερικές φορές ο διακομιστής σας MCP είναι εντάξει, όμως ο πράκτορας επέλεξε τον λάθος ειδικό, ή πέρασε τον μισό χρόνο της συνεδρίας κάνοντας εργασία shell που δεν περιμένατε, ή σιωπηλά κατανάλωσε κόστος σε έναν βρόχο που φαινόταν παραγωγικός απ’ έξω.

Αν δεν μπορείτε να δείτε τη διαφορά, δεν λειτουργείτε πραγματικά ένα σύστημα πρακτόρων. Μαντεύετε.

Έτσι χτίσαμε μια στοίβα παρατηρησιμότητας για τη δική μας ροή εργασίας: Claude Code, Codex, συμβάντα hook του Claude, συμβάντα notify του Codex, εγγενές OpenTelemetry, Grafana Alloy και Grafana Cloud στην άλλη άκρη.

Το ενδιαφέρον κομμάτι δεν είναι «φτιάξαμε έναν πίνακα ελέγχου». Το ενδιαφέρον κομμάτι είναι ότι χρειάστηκε να χωρίσουμε την τηλεμετρία σε δύο διαφορετικές ροές επειδή καμία μεμονωμένη τροφοδοσία δεν μας έδινε την πλήρη εικόνα.

Το Πρόβλημα: Η Τηλεμετρία Πρακτόρων Είναι Κατακερματισμένη

Οι σύγχρονοι πράκτορες κώδικα ήδη εκπέμπουν κάποια τηλεμετρία. Αυτό βοηθά, όμως δεν αρκεί.

Το εγγενές OTEL είναι καλό στο να απαντά ερωτήματα όπως:

• Πόσα αιτήματα κάναμε;
• Πόσο κόστισε μια συνεδρία;
• Πού βρίσκονται τα spans και τα traces;
• Υπήρξε αιχμή στην καθυστέρηση;

Είναι πολύ χειρότερο στο να απαντά ερωτήματα όπως:

• Σε ποιον διακομιστή MCP στηρίχθηκε ο πράκτορας;
• Ήταν αυτή η αστοχία στο Bash, σε ένα ενσωματωμένο εργαλείο αρχείων, ή σε μια κλήση MCP;
• Ποια δεξιότητα πράγματι ενεργοποιήθηκε;
• Ποιος τύπος υπο-πράκτορα δρομολογήθηκε;
• Έκανε η συνεδρία χρήσιμη δουλειά, ή απλώς στροβιλιζόταν χωρίς αποτέλεσμα;

Αυτή η δεύτερη κατηγορία ερωτημάτων ζει πιο κοντά στα hooks παρά στα traces.

Όμως ισχύει και το αντίστροφο: μερικά από τα πιο σημαντικά ερωτήματα απόδοσης ζουν πιο κοντά στα traces παρά στα hooks.

Αν θέλετε να ξέρετε πού πραγματικά συσσωρεύτηκε η καθυστέρηση, ποια spans ήταν αργά, ή αν η συνεδρία κατανάλωσε χρόνο σε κλήσεις μοντέλου έναντι εκτέλεσης εργαλείων, χρειάζεστε δεδομένα traces εξίσου με σημασιολογικά συμβάντα.

Η Αρχιτεκτονική στην Οποία Καταλήξαμε

Τρέχουμε δύο μονοπάτια τηλεμετρίας παράλληλα.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Αυτός ο διαχωρισμός είναι σκόπιμος.

Είναι επίσης ασύμμετρος. Το Claude Code μας δίνει μια πολύ πλουσιότερη επιφάνεια hooks κύκλου ζωής. Το Codex μας δίνει εγγενές OTEL συν μια επιφάνεια notify, οπότε κανονικοποιούμε τα λεπτότερα συμβάντα ολοκλήρωσης γύρου στο ίδιο σχήμα καταγραφής αντί να προσποιούμαστε ότι και οι δύο χρόνοι εκτέλεσης εκθέτουν τους ίδιους ελέγχους.

Το εγγενές OTEL μας δίνει τη βασική ροή: αρχεία καταγραφής και traces από τον ίδιο τον χρόνο εκτέλεσης, συν μετρικές όπου ο χρόνος εκτέλεσης όντως τις εκπέμπει.

Τα συμβάντα hook και notify μας δίνουν το σημασιολογικό επίπεδο: πράγματα όπως τα PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, και τα ταξινομημένα μεταδεδομένα που πραγματικά μας ενδιαφέρουν όταν αποσφαλματώνουμε τη συμπεριφορά πρακτόρων. Το Claude Code συνεισφέρει την πλουσιότερη ροή συμβάντων εδώ. Το Codex συνεισφέρει μια λεπτότερη αλλά ακόμη χρήσιμη κανονικοποιημένη ροή.

Γιατί Υπάρχουν Καν τα Hooks

Ο αγωγός hooks μας εμπλουτίζει τα συμβάντα πριν φτάσουν στο Loki.

Αντί να λέμε απλώς «έτρεξε ένα εργαλείο», ταξινομούμε το συμβάν σε πεδία όπως:

• tool_type: builtin, mcp, skill, agent, bash
• mcp_server: ποιος υποκείμενος διακομιστής MCP χειρίστηκε την κλήση
• bash_cli: η οικογένεια εντολών shell
• subagent_type: τι είδους ειδικός δρομολογήθηκε
• agent_tool: αν η πηγή ήταν Claude Code ή Codex

Αυτό σημαίνει ότι μπορούμε να κάνουμε ερωτήματα που έχουν λειτουργική σημασία:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Αυτά δεν είναι πεδία επίδειξης. Είναι η διαφορά ανάμεσα στο «ο πράκτορας φάνηκε αργός» και στο «ο πράκτορας πέρασε τα τελευταία δέκα λεπτά σε βαριές λειτουργίες git μέσω shell με υψηλό ποσοστό αποτυχίας εργαλείων».

Μια λεπτομέρεια υλοποίησης που φαίνεται πιο περίεργη απ’ όσο είναι: η κοινόχρηστη ροή Loki εξακολουθεί να χρησιμοποιεί το service_name="claude-code-hooks" ως ετικέτα ακόμη και όταν το συμβάν προήλθε από το Codex. Ο πραγματικός διαχωρισμός ανάμεσα στους χρόνους εκτέλεσης συμβαίνει στο agent_tool.

Γιατί το Alloy Βρίσκεται στη Μέση

Το Grafana Alloy δεν είναι απλώς ένας προωθητής σε αυτή τη ρύθμιση. Είναι το όριο πολιτικής.

Στρέφουμε την εγγενή ροή OTEL από το Claude Code και το Codex σε έναν τοπικό διαμεσολαβητή Alloy στο localhost:4318, και έπειτα αφήνουμε το Alloy να καθαρίσει το ωφέλιμο φορτίο πριν το προωθήσει στο Grafana Cloud.

Αυτό έχει σημασία επειδή η ακατέργαστη τηλεμετρία πρακτόρων είναι γεμάτη πεδία υψηλής πληθικότητας που είναι χρήσιμα για ανάλυση αλλά απαίσια ως ευρετηριασμένες ετικέτες:

• session_id
• prompt_id
• αριθμοί tokens
• διάρκειες
• δέσμες παραμέτρων εργαλείων

Αν ευρετηριάσετε τα πάντα, παίρνετε μια έκρηξη ετικετών και μια κακή μέρα.

Οπότε το Alloy κάνει τρία πράγματα για εμάς:

1. Κρατά ευρετηριασμένο ένα πολύ μικρό σύνολο ετικετών χαμηλής πληθικότητας.
2. Μετακινεί θορυβώδη αλλά χρήσιμα πεδία σε δομημένα μεταδεδομένα.
3. Απορρίπτει εντελώς τον καθαρό θόρυβο.

Η σημαντική ιδέα είναι απλή: παρατήρησε περισσότερα, ευρετηρίασε λιγότερα.

Γιατί η Ροή Hook Παρακάμπτει το Alloy

Η ροή hook είναι ήδη διαμορφωμένη για το Loki.

Μέχρι τη στιγμή που το send_event.py σπρώχνει ένα συμβάν, έχουμε ήδη αποφασίσει ποια πεδία αξίζουν μεταχείριση ετικέτας και ποια ανήκουν στο δομημένο σώμα JSON. Εκείνη η ροή πηγαίνει κατευθείαν στην πύλη OTLP του Grafana Cloud αντί να περάσει ξανά από το Alloy.

Οπότε το σύστημα έχει σαφή καταμερισμό εργασίας:

• Το Alloy δαμάζει την ακατέργαστη εγγενή ροή OTEL.
• Ο εμπλουτισμός hook κάνει τα σημασιολογικά συμβάντα αναζητήσιμα.

Αυτό κρατά την αρχιτεκτονική απλούστερη από το να προσπαθείς να περάσεις τα πάντα από ένα μονοπάτι.

Τι Δείχνει Πραγματικά ο Πίνακας Ελέγχου

Το στιγμιότυπο οθόνης παρακάτω προέρχεται από έναν από τους πίνακες ελέγχου παρατηρησιμότητας πίσω από τη ροή εργασίας πρακτόρων μας. Δεν είναι ένα σημείο αναφοράς, και οι αριθμοί είναι απλώς μια στιγμιαία τομή στον χρόνο. Το θέμα είναι το σχήμα των δεδομένων: ροή δραστηριότητας, κλήσεις εργαλείων, αστοχίες, προτροπές, και αναλύσεις ανά πράκτορα, ενσωματωμένα εργαλεία, χρήση MCP, εντολές shell και δεξιότητες.

Το χρήσιμο κομμάτι είναι ότι αυτός ο πίνακας ελέγχου ζει στην ίδια στοίβα Grafana με την υπόλοιπη τηλεμετρία πρακτόρων. Μπορούμε να φιλτράρουμε κατά πράκτορα-πηγή και οικογένεια εργαλείων και να κοιτάξουμε σε όλους τους χρόνους εκτέλεσης χωρίς να επινοήσουμε μια διαφορετική ιστορία παρατηρησιμότητας για κάθε σύστημα.

Γιατί τα Traces Έχουν Περισσότερη Σημασία Απ’ Όσο Φαίνεται Αρχικά

Τα αρχεία καταγραφής μας λένε τι κατηγορία εργασίας συνέβη. Τα traces μας λένε πώς εξελίχθηκε η εργασία με τον χρόνο.

Αυτή η διάκριση έχει σημασία σε συστήματα πρακτόρων επειδή το «αργό» είναι πολύ γενικό για να είναι χρήσιμο.

Ένα trace μπορεί να μας πει αν ο πόνος προήλθε από:

• καθυστέρηση μοντέλου
• χρόνο εκτέλεσης εργαλείου
• επαναλαμβανόμενες επαναπροσπάθειες
• μία ιδιαίτερα δαπανηρή αλληλεπίδραση MCP
• μια μακριά ουρά μικρών λειτουργιών που φαίνονταν ακίνδυνες μεμονωμένα

Στην πράξη χρησιμοποιούμε τη ροή hook και τα traces του Tempo μαζί.

• Τα αρχεία καταγραφής hook απαντούν: τι είδους πράγμα συνέβη;
• Τα traces απαντούν: πού πήγε ο χρόνος;

Ο συνδυασμός είναι αυτό που μετατρέπει την παρατηρησιμότητα από πίνακα ελέγχου σε εξήγηση.

Πού Χωράει το Codex

Το Codex είναι μέρος της ίδιας στοίβας, όμως δεν είναι ταυτόσημο με το Claude Code.

Για το Codex συνδέουμε δύο κομμάτια:

• Εγγενές OTEL από το Codex στο Alloy
• Ένα notify webhook στο codex_notify.py, που αντιστοιχίζει τις ολοκληρώσεις γύρων στο ίδιο σχήμα Loki που χρησιμοποιούμε για συμβάντα hook

Αυτό μας δίνει ένα ενοποιημένο φίλτρο όπως το agent_tool="codex-cli" μέσα στην ίδια ροή καταγραφής.

Η ειλικρινής επιφύλαξη: το ωφέλιμο φορτίο notify του Codex είναι προς το παρόν λεπτότερο από το ωφέλιμο φορτίο hook του Claude Code επειδή δεν είναι το ίδιο είδος επιφάνειας ενσωμάτωσης. Στη σημερινή μας ρύθμιση, οι ολοκληρώσεις γύρων του Codex μπορούν να κανονικοποιηθούν στο κοινό σχήμα, όμως η πλούσια εξαγωγή εργαλείο-προς-εργαλείο εξακολουθεί να είναι καλύτερη στην εγγενή ροή OTEL παρά στη γέφυρα notify.

Αυτό δεν είναι λόγος να αποφύγετε την ανάρτηση. Είναι το νόημα της ανάρτησης. Τα πραγματικά συστήματα παρατηρησιμότητας συναρμολογούνται από ατελή σήματα.

Το Grafana Πάνω από MCP Αλλάζει το Παιχνίδι

Η μεγαλύτερη αλλαγή είναι ότι το Grafana δεν είναι μόνο ένα μέρος που επισκέπτονται άνθρωποι σε ένα πρόγραμμα περιήγησης.

Σε αυτό το αποθετήριο εκθέτουμε επίσης το Grafana μέσω MCP. Αυτό σημαίνει ότι ένας πράκτορας μπορεί να θέσει ερωτήματα απευθείας στο Loki, στο Prometheus και στο Tempo αντί να περιμένει έναν άνθρωπο να επιθεωρήσει χειροκίνητα τους πίνακες ελέγχου πρώτα.

Αυτό μετατρέπει την παρατηρησιμότητα σε ενεργή είσοδο στη ροή εργασίας.

Ένας πράκτορας μπορεί να ρωτήσει:

• Ποιες οικογένειες εργαλείων απέτυχαν περισσότερο την τελευταία ώρα;
• Ποιος διακομιστής MCP κυριάρχησε σε μια συνεδρία;
• Οι πρόσφατες αλλαγές μείωσαν τις αστοχίες εργαλείων ή απλώς μετέφεραν την εργασία σε πιο βαριές διαδρομές shell με τα ίδια λάθη;
• Ποια traces δείχνουν την υψηλότερη καθυστέρηση ή επαναλαμβανόμενες επαναπροσπάθειες;

Μόλις το έχετε αυτό, είστε πολύ κοντά σε έναν βρόχο αυτο-βελτίωσης.

Από τον Πίνακα Ελέγχου στον Βρόχο Ανάδρασης

Αυτό είναι το κομμάτι που βρίσκουμε πιο ενδιαφέρον.

Μόλις η στοίβα παρατηρησιμότητας γίνει αναζητήσιμη από το επίπεδο πρακτόρων, η τηλεμετρία σταματά να είναι μια παθητική επιφάνεια αναφοράς και γίνεται σήμα ελέγχου.

Ο βρόχος μοιάζει ως εξής:

1. Η δραστηριότητα πρακτόρων εκπέμπει traces, μετρικές και εμπλουτισμένα αρχεία καταγραφής hook.
2. Το Grafana αποθηκεύει τα στοιχεία στο Loki, στο Tempo και στο Prometheus όπου υπάρχουν μετρικές.
3. Οι πράκτορες θέτουν ερωτήματα σε αυτά τα στοιχεία μέσω του Grafana MCP.
4. Το σύστημα εντοπίζει κακό μείγμα εργαλείων, εύθραυστες δεξιότητες, αδύναμη δρομολόγηση, ή ροές εργασίας βαριές σε shell που συνεχίζουν να παράγουν αποφεύξιμα λάθη.
5. Οι πράκτορες ή οι χειριστές προσαρμόζουν προτροπές, διαμορφώσεις πρακτόρων, περιγραφές δεξιοτήτων, κανόνες δρομολόγησης ή πρόσβαση σε εργαλεία.
6. Η επόμενη συνεδρία παράγει ένα νέο σχήμα τηλεμετρίας, και ο κύκλος επαναλαμβάνεται.

Έτσι μετακινείσαι από «ενδιαφέρων πίνακας ελέγχου» σε «μετρήσιμο σύστημα βελτίωσης».

Ο στόχος δεν είναι να μεγιστοποιήσετε μία κατηγορία εργαλείων. Είναι να καταλήξετε στο σωστό μείγμα CLI, ενσωματωμένων εργαλείων, κλήσεων MCP και δεξιοτήτων για την εργασία που πράγματι γίνεται.

Τι Μας Επιτρέπει να Απαντήσουμε

Μόλις και οι δύο χρόνοι εκτέλεσης καταλήξουν στην ίδια στοίβα Grafana, μπορούμε να απαντήσουμε λειτουργικά ερωτήματα πολύ πιο γρήγορα:

• Είναι οι αστοχίες συγκεντρωμένες σε μία οικογένεια εργαλείων;
• Δημιουργούν οι ροές εργασίας βαριές σε shell αποφεύξιμα λάθη εκεί όπου θα έπρεπε να υπάρχει ένα εργαλείο υψηλότερου επιπέδου;
• Ποιοι διακομιστές MCP κουβαλούν το φορτίο εργασίας;
• Πληρώνουμε για δραστηριότητα πρακτόρων που δεν παράγει ουσιαστική πρόοδο;
• Είναι μια συνεδρία ανθυγιεινή εξαιτίας του μοντέλου, των εργαλείων ή του επιπέδου ενορχήστρωσης;

Αυτό είναι ιδιαίτερα χρήσιμο σε ροές εργασίας πολλαπλών πρακτόρων, όπου το «ο πράκτορας ήταν απασχολημένος» δεν σας λέει σχεδόν τίποτα.

Αν ένας ειδικός συνεχίζει να δρομολογείται και να παράγει υψηλά ποσοστά αποτυχίας, αυτό είναι πρόβλημα δρομολόγησης ή διαμόρφωσης προτροπής.

Αν ένας διακομιστής MCP κυριαρχεί σε όλες τις κλήσεις, αυτό μπορεί να είναι καλή αρχιτεκτονική ή σημάδι ότι όλα τα υπόλοιπα είναι νεκρό βάρος.

Αν οι αστοχίες εργαλείων εκτοξεύονται ενώ το κόστος παραμένει υψηλό, έχετε λειτουργικό πρόβλημα, όχι πρόβλημα ποιότητας.

Αν η εργασία shell συνεχίζει να αποτυγχάνει με προβλέψιμους, αποφεύξιμους τρόπους εκεί όπου θα έπρεπε να υπάρχει ένα εργαλείο υψηλότερου επιπέδου, αυτό είναι σήμα προϊόντος.

Αν μία δεξιότητα ενεργοποιείται συνεχώς αλλά δεν βελτιώνει τα αποτελέσματα, αυτό είναι σήμα προτροπής ή δρομολόγησης.

Το Πραγματικό Μάθημα

Το βαθύτερο μάθημα εδώ είναι ότι η παρατηρησιμότητα πρακτόρων χρειάζεται τόσο τηλεμετρία χρόνου εκτέλεσης όσο και τηλεμετρία ροής εργασίας.

Η τηλεμετρία χρόνου εκτέλεσης σας λέει τι έκανε το σύστημα.

Η τηλεμετρία ροής εργασίας σας λέει τι νόμιζε ο πράκτορας ότι έκανε.

Χρειαζόμαστε και τα δύο.

Αν κρατάτε μόνο traces και μετρητές, χάνετε το σημασιολογικό επίπεδο. Αν κρατάτε μόνο συμβάντα hook, χάνετε την καθυστέρηση, τα spans και την ευρύτερη εικόνα χρόνου εκτέλεσης.

Και αν κρατάτε και τα δύο αλλά ποτέ δεν τα τροφοδοτείτε πίσω στο επίπεδο πρακτόρων, έχετε παρακολούθηση, όχι προσαρμογή.

Ο συνδυασμός είναι αυτό που κάνει το σύστημα αρκετά επεξηγήσιμο για να λειτουργεί και αρκετά ρυθμίσιμο για να βελτιώνεται.

Τι Εξακολουθεί να Είναι Ατελές

Υπάρχουν ακόμη τραχιές άκρες.

• Δεν περιλαμβάνει κάθε συμβάν hook τα δεδομένα διάρκειας και tokens που θα θέλαμε.
• Μερικές από τις καλύτερες όψεις χρονισμού εξακολουθούν να προέρχονται από traces του Tempo, όχι από τα αρχεία καταγραφής hook.
• Το Codex σήμερα είναι λιγότερο σημασιολογικά πλούσιο από το Claude Code στην εμπλουτισμένη ροή συμβάντων.
• Το στιγμιότυπο οθόνης του πίνακα ελέγχου είναι μια ζωντανή επιφάνεια λειτουργιών, όχι ένα στιλβωμένο τεχνούργημα μάρκετινγκ.

Αυτό το τελευταίο σημείο είναι σκόπιμο. Προτιμούμε να δείξουμε τον πραγματικό πίνακα οργάνων παρά να προσποιηθούμε ότι τα συστήματα πρακτόρων είναι μαγικά αυτο-επεξηγούμενα.

Γιατί Αυτό Έχει Σημασία για το Maguyva

Το Maguyva αφορά το να δίνει στους πράκτορες καλύτερη ευφυΐα κώδικα. Όμως μόλις οι πράκτορες κάνουν πραγματικά χρήσιμη δουλειά, εμφανίζεται αμέσως μια νέα απαίτηση: χρειάζεται να δείτε πώς συμπεριφέρονται.

Η ποιότητα αναζήτησης, η ποιότητα δρομολόγησης, η επιλογή εργαλείων και η αποδοτικότητα πλαισίου γίνονται όλα παρατηρήσιμα προβλήματα.

Γι’ αυτό πιστεύουμε ότι αξίζει να γράψουμε γι’ αυτό. Η μελλοντική στοίβα πρακτόρων δεν είναι μόνο προτροπές και εργαλεία. Είναι προτροπές, εργαλεία, και το επίπεδο οργανολογίας που σας λέει αν όλο αυτό λειτουργεί.

Αν χτίζετε σοβαρές ροές εργασίας πρακτόρων, η παρατηρησιμότητα δεν είναι προαιρετική υποδομή. Είναι μέρος του προϊόντος.