diff --git a/README.md b/README.md index 8e62c06..6d8c6f7 100644 --- a/README.md +++ b/README.md @@ -3,33 +3,51 @@ [![Contributor-Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md) [![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com) -Application Simulator allows you to rapidly create a set of interacting services, databases and load generators to -simulate application deployments of any size and form. +Application Simulator allows you to rapidly create a set of interacting +services, databases and load generators to simulate application deployments of +any size and form. -Unlike other simulators or demo applications it is not focused around a specific kind of application, like a blog, task -list, web shop or banking app. Instead, Application Simulator is driven by configuration files that define the behavior +Unlike other simulators or demo applications it is not focused around a specific +kind of application, like a blog, task list, web shop or banking app. Instead, +Application Simulator is driven by configuration files that define the behavior of the components of your application. -This is especially useful for use cases, where you care less about the business logic to be mimicked, but the interaction -of the different components that make up an application. +This is especially useful for use cases, where you care less about the business +logic to be mimicked, but the interaction of the different components that make +up an application. This includes the following use cases: -- Tailored demo environments for observability, e.g. instrumenting all services with OpenTelemetry and visualizing the - data in your preferred backend. -- Complex simulated environments for in-cluster network experiments, e.g. testing out new features of cilium. +- Tailored demo environments for observability, e.g. instrumenting all services + with OpenTelemetry and visualizing the data in your preferred backend. +- Complex simulated environments for in-cluster network experiments, e.g. + testing out new features of cilium. ## Quick Start -You can use application simulator with your preferred container orchestration, since all components are available as -container images. We provide the best experience for docker compose and kubernetes. Pick one of them for a quick start! +You can use application simulator with your preferred container orchestration, +since all components are available as container images. We provide the best +experience for docker compose and kubernetes. Pick one of them for a quick +start! - [kubernetes quick start](./docs/quick-start/kubernetes.md) - [docker compose quick start](./docs/quick-start/docker-compose.md) +> [!NOTE] +> +> You can use the +> [container images](https://github.com/orgs/cisco-open/packages?repo_name=app-simulator) +> published as part of this project without the generators for kubernetes and +> docker compose. Both are convenience functions! +> +> If you only need a container image that simulates the behavior of an +> application, check out the +> [standalone container quick start](./docs/quick-start/standalone-container/README.md). + ## Tutorial -After you have tried out application simulator with the quick start, you can learn using it with the step by step tutorial: +After you have tried out application simulator with the quick start, you can +learn using it with the step by step tutorial: 1. [Two java services](./docs/tutorial/1-two-java-services.md) 2. [A database and more services](./docs/tutorial/2-a-database-and-more-services.md) @@ -38,14 +56,19 @@ After you have tried out application simulator with the quick start, you can lea ## Configuration specification -Application simulator is driven by configuration files that allow you to describe a microservice architecture and -then run it with your preferred container orchestration. The configuration file follows a [specification](./docs/specification.md) +Application simulator is driven by configuration files that allow you to +describe a microservice architecture and then run it with your preferred +container orchestration. The configuration file follows a +[specification](./docs/specification.md) ## Contribute -If you'd like to contribute to this project, check out our [contribution guidelines](./CONTRIBUTING.md). +If you'd like to contribute to this project, check out our +[contribution guidelines](./CONTRIBUTING.md). ## Support -If you have any questions or concerns, get in touch with us by [raising an issue](https://github.com/cisco-open/app-simulator/issues). -If you want to report a security issue, please follow our [security policy](./SECURITY.md) +If you have any questions or concerns, get in touch with us by +[raising an issue](https://github.com/cisco-open/app-simulator/issues). If you +want to report a security issue, please follow our +[security policy](./SECURITY.md) diff --git a/docs/quick-start/standalone-container/README.md b/docs/quick-start/standalone-container/README.md new file mode 100644 index 0000000..e72dddf --- /dev/null +++ b/docs/quick-start/standalone-container/README.md @@ -0,0 +1,152 @@ +# Standalone container quick start + +While you can build complex multi tier application simulations with the +generators for [kubernetes](kubernetes.md) or +[docker compose](docker-compose.md) it is possible to use the +[cisco-open/app-simulator container images](https://github.com/orgs/cisco-open/packages?repo_name=app-simulator) +standalone. In this document you will find a few standalone examples that +demonstrate this use case. + +## Table Of Contents + +## Java application with OpenTelemetry + +If you are looking for a way to generate some sample telemetry with the +[OpenTelemetry Java agent](https://opentelemetry.io/docs/zero-code/java/agent/), +create a `config.json` with the following content: + +```json +{ + "endpoints": { + "http": { + "/my/endpoint": [ + "http://github.com/", + "sleep,1000", + { + "call": "error,500,oops", + "probability": 0.25 + } + ] + } + }, + "name": "frontend", + "type": "java" +} +``` + +In the same folder, run the +[app-simulator-services-java](https://github.com/cisco-open/app-simulator/pkgs/container/app-simulator-services-java) +with Docker: + +```shell +docker run -t -i --rm --volume ${PWD}/config.json:/config.json -p 8080:8080 ghcr.io/cisco-open/app-simulator-services-java:latest +``` + +This will start a Java based webserver listening on port 8080 for requests. Run +the following command a few times: + +```shell +curl -v localhost:8080/my/endpoint +``` + +You will see that 1 in 4 requests will return a `500 Server Error`. + +Add the +[OpenTelemetry Java agent](https://opentelemetry.io/docs/zero-code/java/agent/) +to create telemetry for the service. + +Stop the currently running container and download the Java agent: + +```shell +https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar +``` + +Restart the container with the following settings: + +```shell +docker run -t -i --rm \ + --volume ${PWD}/config.json:/config.json \ + --volume ${PWD}/opentelemetry-javaagent.jar:/opt/opentelemetry-javaagent.jar \ + -e JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry-javaagent.jar" \ + -e OTEL_SERVICE_NAME="my-simulated-app" \ + -e OTEL_TRACES_EXPORTER=logging \ + -e OTEL_METRICS_EXPORTER=logging \ + -e OTEL_LOGS_EXPORTER=logging \ + -p 8080:8080 \ + ghcr.io/cisco-open/app-simulator-services-java:latest +``` + +This will start the Java based webserver with OpenTelemetry enabled. Re-run the +previous command to send some requests: + +```shell +curl -v localhost:8080/my/endpoint +``` + +The Java agent will print telemetry to the console, e.g.: + +```shell +[otel.javaagent 2024-12-30 14:31:24:972 +0000] [qtp1467981309-27] INFO io.opentelemetry.exporter.logging.LoggingSpanExporter - 'GET' : bbf7fc4f97e47a2bdef475f928099d62 31baa1f78b9c2701 SERVER [tracer: io.opentelemetry.jetty-11.0:2.11.0-alpha] AttributesMap{data={url.scheme=http, thread.name=qtp1467981309-27, network.protocol.version=1.1, network.peer.port=61224, user_agent.original=curl/8.7.1, http.request.method=GET, server.port=8080, url.path=/my/endpoint, thread.id=27, error.type=500, server.address=localhost, client.address=172.17.0.1, http.response.status_code=500, network.peer.address=172.17.0.1}, capacity=128, totalAddedValues=14} +``` + +As a final step, start +[jaeger](https://www.jaegertracing.io/docs/getting-started/) and send traces to +it via OTLP: + +```shell +docker run --rm --name jaeger \ + -p 16686:16686 \ + -p 4317:4317 \ + -p 4318:4318 \ + --network app-sim \ + jaegertracing/all-in-one:1.64.0 +``` + +and + +```shell +docker run -t -i --rm \ + --volume ${PWD}/config.json:/config.json \ + --volume ${PWD}/opentelemetry-javaagent.jar:/opt/opentelemetry-javaagent.jar \ + -e JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry-javaagent.jar" \ + -e OTEL_SERVICE_NAME="my-simulated-app" \ + -e OTEL_TRACES_EXPORTER=otlp \ + -e OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://jaeger:4318/v1/traces \ + -e OTEL_METRICS_EXPORTER=none \ + -e OTEL_LOGS_EXPORTER=none \ + -p 8080:8080 \ + --network app-sim \ + ghcr.io/cisco-open/app-simulator-services-java:latest +``` + +A span for a request that returned a `500 Server Error` looks like the following +in jaeger: + +![A screenshot of a span in jaeger showing the span data for the error](spans-in-jaeger.png) + +## curl loader as base image + +Like any other container image, you can use +[cisco-open/app-simulator container images](https://github.com/orgs/cisco-open/packages?repo_name=app-simulator) +as base images, e.g.: + +```Dockerfile +FROM ghcr.io/cisco-open/app-simulator-loaders-curl:latest + +WAIT=0 +SLEEP=5 +URLS=https://github.com/cisco-open/app-simulator +``` + +Build the docker image: + +```shell +docker build -t my-load-generator . +``` + +Run your custom load generator for +: + +```shell +docker run --rm -t -i my-load-generator +``` diff --git a/docs/quick-start/standalone-container/spans-in-jaeger.png b/docs/quick-start/standalone-container/spans-in-jaeger.png new file mode 100644 index 0000000..49bd7fc Binary files /dev/null and b/docs/quick-start/standalone-container/spans-in-jaeger.png differ