Playbook: data stores and events
The questions, in the user's words: "We are renaming a column of the orders table: what reads or writes it, in which services?" and "I am changing the payload of the orders.placed topic: who publishes it, and who consumes it?"
What you get at the end: every method that reads, writes or deletes a store, across services and through ORM repositories; and for a message topic, its publishers and handlers, plus the events that have only one side.
Words used on this page: an event is a message one piece of code publishes on a named topic (or queue) and other code handles; a broker is the server that carries it (Kafka, RabbitMQ, Redis and others).
In recorded agent sessions (mostly Niro's own development, labelled by hand by one agent, about plus or minus 10%), agents asked data and event questions with text search: 10 of 21 calls were code_grep and 1 was list_data_resources. The tools below answer these directly.
A table across services
niro ask get_data_resource_usage resource_fqn=orders
sql:table:orders
read by (4):
LedgerDao.openOrders
OrderRepository.findByStatus
OrderRepository.findLate
OrderStoreService.open
written by (2):
SharedTables.createOrder
OrderStoreService.save
deleted by (1):
OrderStoreService.remove
These are in three services: main (SharedTables, plain SQL), jdbc (LedgerDao, plain SQL) and spring-data-jpa (OrderRepository and OrderStoreService, through Spring Data). findByStatus is a derived query: its SQL comes from the method's name and the entity's @Table(name = "orders"), and no line of code names the table.
Then, for each method, get_blast_radius method_fqn=... direction=upstream answer=names gives what calls it.
What grep would do instead: grep -rniw orders prints 53 lines in the Java files, mostly route paths (/api/orders), host names (orders-api) and topic names. The SQL lines are in there, but OrderStoreService.save and remove are not: they call repository.save(order) and repository.deleteById(id).
A topic: who publishes and who handles
niro ask get_event_producers_and_handlers name=invoices.created
rabbitmq:invoices.created [spring-amqp]
published by (1):
EventPublishers.invoiceCreated
handled by (1):
InvoiceListener.onInvoice
The publisher is in main (rabbitTemplate.convertAndSend("invoices.created", ...)) and the handler in spring-amqp (@RabbitListener(queues = "invoices.created")).
A trap a text search shows you
niro ask get_event_producers_and_handlers name=orders.placed
kafka:orders.placed [kafka-clients]
published by (1):
EventPublishers.orderPlaced
handled by (1):
OrderAuditConsumer.run
A text search shows a second line that looks like a publish: TrapCaller.run calls outbox.send("orders.placed", "x"). But outbox is a class of the project's own that happens to be called KafkaTemplate, not Spring's Kafka client. Niro recognises a publish by the type the call is made on, so it leaves this one out. An agent with only a text search has to read the class to rule it out; in the A/B (task p-07), the shell-only agents did, in both runs.
And where Niro misses, today
The same topic has two more consumers that this release does not read: a Kafka Streams topology (builder.stream("orders.placed")) and a Camel route (from("kafka:orders.placed?...")). Both are recorded gaps. A text search for the topic name finds them, so for a payload change, run code_grep pattern=orders.placed answer=locations as well.
Events with one side
niro ask find_orphaned_events limit=8
20 event(s) with only one side:
carts.recovered [MESSAGE_QUEUE, nats]
handled here, nothing publishes it
giftcards.issued [MESSAGE_PUBLISH, spring-kafka]
published here, nothing handles it
...
One side missing means one of three things, and the answer says so: the other side is outside this project, its library is not recognised, or the two sides name the event differently.
Why the answer is complete, and where it is not
- Stores and events are read from known libraries and forms. Each language page lists them, see Supported languages. A form not listed (like the two consumers above) is missing without a warning.
- Topics are matched by name. A topic name built at run time, or read from a setting Niro has no value for, cannot be matched.
- An in-process event (a framework's own event bus) never leaves its service, and the answer marks it so.
Cost
What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in Tokens, speed and accuracy.
Related
Playbook: debug a wrong value, Playbook: learn a new codebase, FAQ: wrong or missing answers.