-
Notifications
You must be signed in to change notification settings - Fork 74
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(docs): update pokeshop and kafka trigger docs (#3129)
* wip - update pokeshop docs * Updating Pokeshop + Kafka docs * Apply suggestions from code review Co-authored-by: Julianne Fermi <julianne@kubeshop.io> Co-authored-by: Adnan Rahić <adnan@kubeshop.io> --------- Co-authored-by: Julianne Fermi <julianne@kubeshop.io> Co-authored-by: Adnan Rahić <adnan@kubeshop.io>
- v1.7.1
- v1.7.0
- v1.7.0-rc.2
- v1.7.0-rc.1
- v1.6.2
- v1.6.1
- v1.6.0
- v1.5.6-rc.2
- v1.5.6-rc.1
- v1.5.5
- v1.5.4
- v1.5.3
- v1.5.2
- v1.5.2-rc.3
- v1.5.2-rc.2
- v1.5.2-rc.1
- v1.5.1
- v1.5.0
- v1.4.5-rc.1
- v1.4.4
- v1.4.4-rc.1
- v1.4.3
- v1.4.3-rc.3
- v1.4.3-rc.2
- v1.4.3-rc.1
- v1.4.2
- v1.4.1
- v1.4.1-rc.3
- v1.4.1-rc.2
- v1.4.1-rc.1
- v1.4.0
- v1.3.2
- v1.3.2-rc.8
- v1.3.2-rc.7
- v1.3.2-rc.6
- v1.3.2-rc.5
- v1.3.2-rc.4
- v1.3.2-rc.3
- v1.3.2-rc.2
- v1.3.2-rc.1
- v1.3.1
- v1.3.1-rc.3
- v1.3.1-rc.2
- v1.3.1-rc.1
- v1.3.0
- v1.3.0-rc.1
- v1.2.0
- v1.2.0-rc.1
- v1.1.1-rc.1
- v1.1.0
- v1.1.0-rc.1
- v1.0.1-rc.5
- v1.0.1-rc.4
- v1.0.1-rc.3
- v1.0.1-rc.2
- v1.0.1-rc.1
- v1.0.0
- v0.16.3-rc.8
- v0.16.3-rc.7
- v0.16.3-rc.6
- v0.16.3-rc.5
- v0.16.3-rc.4
- v0.16.3-rc.3
- v0.16.3-rc.2
- v0.16.3-rc.1
- v0.16.2
- v0.16.2-rc.2
- v0.16.2-rc.1
- v0.16.1
- v0.16.1-rc.1
- v0.16.0
- v0.15.17
- v0.15.17-rc.1
- v0.15.10-rc.3
- v0.15.10-rc.2
- v0.15.10-rc.1
- v0.15.9
- v0.15.9-rc.1
- v0.15.8
- v0.15.8-rc.1
- v0.15.7
- v0.15.6
- v0.15.6-rc.2
- v0.15.6-rc.1
- v0.15.5
- v0.15.5-rc.3
- v0.15.5-rc.2
- v0.15.5-rc.1
- v0.15.4
- v0.15.4-rc.3
- v0.15.4-rc.2
- v0.15.4-rc.1
- v0.15.3
- v0.15.3-rc.1
- v0.15.2
- v0.15.2-rc.1
- v0.15.1
- v0.15.1-rc.3
- v0.15.1-rc.2
- v0.15.1-rc.1
- v0.15.0
- v0.15.0-rc.3
- v0.15.0-rc.2
- v0.15.0-rc.1
- v0.14.10-rc.1
- v0.14.9
- v0.14.9-rc.2
- v0.14.9-rc.1
- v0.14.8
- v0.14.8-rc.1
- v0.14.7
- v0.14.7-rc.12
- v0.14.7-rc.11
- v0.14.7-rc.10
- v0.14.7-rc.9
- v0.14.7-rc.8
- v0.14.7-rc.7
- v0.14.7-rc.6
- v0.14.7-rc.5
- v0.14.7-rc.4
- v0.14.7-rc.3
- v0.14.7-rc.2
- v0.14.7-rc.1
- v0.14.6
- v0.14.6-rc.3
- v0.14.6-rc.2
- v0.14.6-rc.1
- v0.14.5
- v0.14.5-rc.4
- v0.14.5-rc.3
- v0.14.5-rc.2
- v0.14.5-rc.1
- v0.14.4
- v0.14.4-rc.2
- v0.14.4-rc.1
- v0.14.3
- v0.14.3-rc.2
- v0.14.3-rc.1
- v0.14.2
- v0.14.1
- v0.14.1-rc.1
- v0.14.0
- v0.14.0-rc.2
- v0.14.0-rc.1
- v0.13.10
- v0.13.9
- v0.13.9-rc.11
- v0.13.9-rc.10
- v0.13.9-rc.9
- v0.13.9-rc.7
- v0.13.9-rc.6
- v0.13.9-rc.5
- v0.13.9-rc.4
- v0.13.9-rc.3
- v0.13.9-rc.2
- v0.13.9-rc.1
- v0.13.8
- v0.13.8-rc.1
- nightly
1 parent
84198fc
commit 44a1a34
Showing
12 changed files
with
131 additions
and
16 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+482 KB
...s/live-examples/pokeshop/images/import-pokemon-from-stream-database-latency.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+466 KB
docs/docs/live-examples/pokeshop/images/import-pokemon-from-stream-get-pokeapi.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+513 KB
...s/live-examples/pokeshop/images/import-pokemon-from-stream-message-received.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+252 KB
docs/docs/live-examples/pokeshop/images/import-pokemon-from-stream-trace.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+465 KB
.../live-examples/pokeshop/images/import-pokemon-from-stream-use-case-executed.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
102 changes: 102 additions & 0 deletions
102
docs/docs/live-examples/pokeshop/use-cases/import-pokemon-from-stream.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,102 @@ | ||
# Pokeshop API - Import Pokemon from Stream | ||
|
||
This use case showcases a more complex scenario involving an async process. Usually, when working with microservices, there are use cases where some of the processing needs to happen asynchronously. For example, when triggering a user notification, generating reports or processing a payment order. With this endpoint, we provide an example of how users can implement trace-based testing for such scenarios. | ||
|
||
Here the process listens to a stream, and whenever an event is read from it, the following process is triggered: | ||
```mermaid | ||
sequenceDiagram | ||
participant Stream as Kafka | ||
participant Worker as Stream Worker | ||
participant ExternalAPI as PokeAPI | ||
participant Database as Postgres | ||
Stream->>Worker: read "import" message | ||
Worker->>ExternalAPI: get pokemon info | ||
ExternalAPI-->>Worker: pokemon info | ||
Worker->>Database: save pokemon | ||
Database-->>Worker: pokemon saved | ||
``` | ||
|
||
You can trigger this use case by sending a message to Kafka on the `pokemon` topic with the following message value: | ||
```json | ||
{ | ||
"id": 143 | ||
} | ||
``` | ||
|
||
## Building a Test for This Scenario | ||
|
||
Using Tracetest, we can [create a test](../../../web-ui/creating-tests.md) that will produce a message to Kafka on `pokemon` topic and validate the following properties: | ||
- The worker should read the import task. | ||
- PokeAPI should return a valid response. | ||
- The database should respond with low latency (< 200ms). | ||
|
||
### Traces | ||
|
||
Running these tests for the first time will create a distributed trace like the image below, where you can see spans for the stream messaging, the PokeAPI (external API) call and database calls. | ||
|
||
![](../images/import-pokemon-from-stream-trace.png) | ||
|
||
### Assertions | ||
|
||
With this trace, we can build [assertions](../../../concepts/assertions.md) with Tracetest and validate the API and Worker behavior: | ||
|
||
- **A message was received from Kafka stream:** | ||
![](../images/import-pokemon-from-stream-message-received.png) | ||
|
||
- **Import Pokemon use case was triggered**: | ||
- ![](../images/import-pokemon-from-stream-use-case-executed.png) | ||
|
||
- **PokeAPI should return a valid response:** | ||
![](../images/import-pokemon-from-stream-get-pokeapi.png) | ||
|
||
- **The database should respond with low latency (< 200ms):** | ||
![](../images/import-pokemon-from-stream-database-latency.png) | ||
|
||
Now you can validate this entire use case. | ||
|
||
### Test Definition | ||
|
||
If you want to replicate this entire test with Tracetest, you can replicate these steps in the Web UI or using the CLI, saving the following test definition as the file `test-definition.yml` and running: | ||
|
||
```sh | ||
tracetest run test -f test-definition.yml | ||
``` | ||
|
||
```yaml | ||
type: Test | ||
spec: | ||
id: a97syfdkjad | ||
name: Import a Pokemon reading a Stream | ||
description: Import a Pokemon via Stream | ||
trigger: | ||
type: kafka | ||
kafka: | ||
brokerUrls: | ||
- stream:9092 | ||
topic: pokemon | ||
headers: [] | ||
messageKey: snorlax-key | ||
messageValue: "{\"id\":143}" | ||
specs: | ||
- selector: span[tracetest.span.type="messaging" name="pokemon process" messaging.system="kafka" messaging.destination="pokemon" messaging.destination_kind="topic" messaging.operation="process"] | ||
name: A message was received from Kafka stream | ||
assertions: | ||
- attr:messaging.system = "kafka" | ||
- selector: span[tracetest.span.type="general" name="import pokemon"] | ||
name: Import Pokemon use case was triggered | ||
assertions: | ||
- attr:name = "import pokemon" | ||
- selector: span[tracetest.span.type="http" name="GET" http.method="GET"] | ||
name: PokeAPI should return a valid response | ||
assertions: | ||
- attr:http.response.body = '{"name":"snorlax"}' | ||
- attr:http.status_code = 200 | ||
- selector: span[tracetest.span.type="database"] | ||
name: The database should respond with low latency (< 200ms) | ||
assertions: | ||
- attr:tracetest.span.duration <= 200ms | ||
|
||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters