User Guide: Technical Testing Notes for Surrogate Keys, Grafana, and Logs - abeedal/Abeedal GitHub Wiki
User Guide: Technical Testing Notes for Surrogate Keys, Grafana, and Logs
Surrogate Keys Introduction This user guide provides step-by-step instructions for testers to run tests related to surrogate keys, as well as how to use Grafana and logs to monitor and analyse data. The guide assumes familiarity with the relevant technologies and concepts.
In our services, surrogate keys refer to entities, and are used to control caching at Fastly.
More details on how we use surrogate keys, see aff-services-mono Readme.md
To test surrogate keys, follow these steps:
Clone the aff-services-mono repository from here
Open the root folder in the terminal.
Use nvm to ensure the correct version of Node.js is being used.
Run npm clean-install to install dependencies.
Open the libs > surrogate-keys folder in the integrated terminal.
Run the Jest tests by executing npm run test.
After the tests are complete, run npm run test:e2e to ensure cache invalidation is working properly.
Our surrogate keys take two forms:
'Single keys' of the form $entity-$id for single entities (e.g. "Bookmaker-1")
'List keys' of the form $parentEntity-$parentId:$childEntity for lists of related entities (e.g. "Competition-1:Event" for the list of events related to the Competition entity with ID 1).
The subscriber should trigger the creation of purge/surrogate keys on create / update / delete events for entities.
For new entities:
Purge list keys for many-to-one relationships. (A multiple selection with events, which can have teams, competitions, and sports.)
Purge list keys for many-to-many relationships. (A sport can have multiple editors who provide multiple picks.)
For existing entities:
Purge any single entity keys when deleting.
Purge any single entity keys when editing.
Manual checks
many-to-one relationships
Create a multiple in the Events Service
- Confirm a surrogate key has been created in the data store for that entity
Get to the Multiples endpoint by Id and confirm surrogate key is in the headers
Confirm same Surrogate key is send to Fastly (CDN)
edit many-to-one relationships
- Confirm a surrogate key present in the data store for that entity
Edit a multiple in the Events Service
- Confirm a new surrogate key has been created in the data store for that updated entity
Get to the Multiples endpoint by Id and new confirm surrogate key is in the headers
Confirm new Surrogate key is send to Fastly (CDN)
delete many-to-one relationships
- Needs confirming
many-to-many relationships
Create an Event in the Events Service
- Confirm a surrogate key has been created in the data store for that entity
Get to the Event endpoint by Id and confirm surrogate key is in the headers
Confirm same Surrogate key is send to Fastly (CDN)
single relationship (Bookmaker)
Create a bookmaker in the Offers Service
- Confirm a surrogate key has been created in the data store for that entity
Get to the Bookmaker by Id endpoint by Id and confirm surrogate key is in the headers
Confirm same Surrogate key is send to Fastly (CDN)
Grafana and Logs Grafana and Logs Grafana is a data visualisation tool used to display and monitor data. Logs are used to record events and system messages. Follow these steps to use Grafana and logs:
Dashboards
Open Grafana and log in using Google.
Expand the left-hand panel and select "Dashboards" > "Browse."
Choose "Affiliates" and select either "GSP Imports" or "GSP Imports-traces" to view the appropriate dashboard.
To edit a dashboard, select the dropdown for the chart and choose "Edit." To view a trace, right-click it and select "Open in new tab."
Expand traces to view further details.
Traces - Jaeger
Traces can be found in standalone Jaeger or in Jaegar through Grafana. An in depth article about traces can be found here
Open Grafana and log in using Google.
Click on the Explore icon in the left-hand panel
Select Jaeger from the dropdown
Confirm Query type is set to TraceID
Add a traceId and run the query using the Run Query button
Logs - Loki
In Grafana, navigate to "Explore" in the left-hand panel.
In the Labels section, select the desired query options, then click "Run Query."
Select "Loki" from the dropdown at the top of the screen.
Use the beta builder to select query options, or use the code option if you know the queries to run.
Use the timer icon near the blue query button to search for logs from the last x minutes or hours.
Example Log Queries:
To filter logs by container, use:
arduinoCopy code{container="events-service"} To extract JSON fields from logs, use:
arduinoCopy code| logfmt | line_format "{{ .log }}" | regexp " - (?P<json_field>.*)" | json_field!="" | line_format "{{ .json_field }}" | json | error="" To filter logs by trace flags, use:
arduinoCopy code| trace_flags = "01" To filter logs by trace ID, use:
arduinoCopy code| trace_id = "678472f7bd0404333a9e77c0e6e71cc2" To filter logs by ECS cluster, use:
arduinoCopy code| ecs_cluster = "uat-ecs" You can add to the above queries to drill down further into the logs.