From b5aa85f50aa528ac18cf2e3b6cba5f9f4a5754af Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Sep 2024 12:46:52 +0200 Subject: [PATCH 1/5] docs(getting-started): update install --- docs/docs/getting-started/installation.mdx | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index b8ac628c68..bc4d958e29 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -229,7 +229,9 @@ Make sure to run tests using the internal Kubernetes service networking eg: `htt -Set the `` and `` to your desired values. +Set the `` to your desired value, or omit it to install in the `default` namespace. + +The `` is set to `agent` to simplify the getting started guide. ` and `` to your desired values. > {`helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update && \\ -helm install -n tracetestcloud/tracetest-agent \\ +helm install agent -n tracetestcloud/tracetest-agent \\ --set agent.apiKey= --set agent.environmentId=`} -The Tracetest Agent is running in Kubernetes and ready to accept traces. +The Tracetest Agent is running in Kubernetes and ready to accept traces. With this installation of using `agent` as the ``, the trace ingestion endpoints will be: -gRPC: `http://:4317` +gRPC: `http://agent-tracetest-agent:4317` -HTTP: `http://:4318/v1/traces` +HTTP: `http://agent-tracetest-agent:4318/v1/traces` :::note K8s Network Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. -Make sure to run tests using the internal Kubernetes service networking eg: `http://api.default.svc.cluster.internal:port`. +Make sure to run tests using the internal Kubernetes service networking eg: `http://pokeshop-pokemon-api:8081`. ::: @@ -335,19 +337,19 @@ git clone --depth 1 https://github.com/kubeshop/pokeshop.git cd pokeshop/helm-charts helm dependency update -helm install -n -f values.yaml --create-namespace . +helm install -n -f values.yaml --create-namespace pokeshop . ``` To access the Pokeshop API run a `port-forward`: ```bash -kubectl port-forward svc/api 8081:8081 +kubectl port-forward svc/pokeshop-pokemon-api 8081:8081 ``` - [`https://app.tracetest.io/`](https://app.tracetest.io) - Access the Tracetest Web UI. Sign up and create an organization. - [`http://localhost:8081`](http://localhost:8081) - The Pokeshop API demo is port forwarded from Kubernetes to `localhost` on this port. -- To run tests you will use the Kubernetes internal network and the service name, `http://http://api.default.svc.cluster.internal:8081`. -- `tracetest-agent.default.svc.cluster.local:4317` - Trace ingestion URL where Tracetest Agent will accept traces. +- To run tests you will use the Kubernetes internal network and the service name, `http://pokeshop-pokemon-api:8081`. +- `http://agent-tracetest-agent:4317` - Trace ingestion URL where Tracetest Agent will accept traces. From d1f85d0dc4cce625a20cfd9ed888b7d22dd5e1f2 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Sep 2024 16:27:40 +0200 Subject: [PATCH 2/5] docs(install): update k8s and helm --- docs/docs/getting-started/installation.mdx | 16 ++-- docs/docs/install/cloud-helm.mdx | 58 +++++++++++++ docs/docs/install/kubernetes.mdx | 82 +++++++++++++++---- .../install/{helm.mdx => on-prem-helm.mdx} | 10 +-- docs/sidebars.js | 7 +- 5 files changed, 144 insertions(+), 29 deletions(-) create mode 100644 docs/docs/install/cloud-helm.mdx rename docs/docs/install/{helm.mdx => on-prem-helm.mdx} (94%) diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index bc4d958e29..d830db4155 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -217,11 +217,13 @@ spec: The Tracetest Agent is running in Kubernetes and ready to accept traces. -gRPC: `http://:4317` +gRPC: `http://tracetest-agent.default.svc.cluster.local:4317` -HTTP: `http://:4318/v1/traces` +HTTP: `http://tracetest-agent.default.svc.cluster.local:4318/v1/traces` :::note K8s Network +Make sure to check use the correct `` if you edit the Tracetest Agent `service` name. + Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. Make sure to run tests using the internal Kubernetes service networking eg: `http://api.default.svc.cluster.internal:port`. ::: @@ -229,17 +231,13 @@ Make sure to run tests using the internal Kubernetes service networking eg: `htt -Set the `` to your desired value, or omit it to install in the `default` namespace. - -The `` is set to `agent` to simplify the getting started guide. - {`helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update && \\ -helm install agent -n tracetestcloud/tracetest-agent \\ +helm install agent tracetestcloud/tracetest-agent \\ --set agent.apiKey= --set agent.environmentId=`} @@ -325,7 +323,7 @@ kubectl port-forward svc/api 8081:8081 - [`https://app.tracetest.io/`](https://app.tracetest.io) - Access the Tracetest Web UI. Sign up and create an organization. - [`http://localhost:8081`](http://localhost:8081) - The Pokeshop API demo is port forwarded from Kubernetes to `localhost` on this port. -- To run tests you will use the Kubernetes internal network and the service name, `http://http://api.default.svc.cluster.internal:8081`. +- To run tests you will use the Kubernetes internal network and the service name, `http://api.default.svc.cluster.internal:8081`. - `tracetest-agent.default.svc.cluster.local:4317` - Trace ingestion URL where Tracetest Agent will accept traces. @@ -337,7 +335,7 @@ git clone --depth 1 https://github.com/kubeshop/pokeshop.git cd pokeshop/helm-charts helm dependency update -helm install -n -f values.yaml --create-namespace pokeshop . +helm install -f values.yaml --create-namespace pokeshop . ``` To access the Pokeshop API run a `port-forward`: diff --git a/docs/docs/install/cloud-helm.mdx b/docs/docs/install/cloud-helm.mdx new file mode 100644 index 0000000000..5e563e64e8 --- /dev/null +++ b/docs/docs/install/cloud-helm.mdx @@ -0,0 +1,58 @@ +--- +id: cloud-helm +title: Install with Helm +hide_table_of_contents: false +description: Installation and deployment instructions for using Helm to deploy Enterprise self-hosted Tracetest and use the On-Prem Tracetest Control Plane / Dashboard. +keywords: + - tracetest + - trace-based testing + - observability + - distributed tracing + - testing +image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg +--- + +This guide explains how to install a Tracetest Agent in your Kubernetes environment with Helm. It will install a Tracetest Agent in your infrastructure and use the Cloud-based managed Tracetest Control Plane and Dashboard. + +## Prerequisites + +- A running Kubernetes cluster. +- A Tracetest license key. If you don't have one, you can request a trial license key [here](https://tracetest.io/on-prem-installation). +- Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl). +- Install [Helm](https://helm.sh/). + +## Install Tracetest Agent with Helm + +The [main chart for this repository is called `tracetest-agent`](https://github.com/kubeshop/tracetest-cloud-charts/tree/main/charts/tracetest-agent) and contains all components necessary to run Tracetest Agent in a cluster that fits the [deployment architecture](/install/deployment-architecture). + +```js title="Terminal" +helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update && \ + +helm install -n tracetestcloud/tracetest-agent \ +--set agent.apiKey= --set agent.environmentId= +``` + +If you use `agent` as the `` with this installation, the trace ingestion endpoints will be: + +gRPC: `http://agent-tracetest-agent:4317` + +HTTP: `http://agent-tracetest-agent:4318/v1/traces` + +## Configuration + +Configure the Helm installation with the `values.yaml` file. View the [`values.yaml` default values, here.](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/charts/tracetest-agent/values.yaml) + +
+ + Click to expand the `values.yaml` default values. + + +```yaml +agent: + apiKey: "apiKey" + environmentId: "environment-id" + serverURL: "https://app.tracetest.io" + skipVerify: false +``` + +
diff --git a/docs/docs/install/kubernetes.mdx b/docs/docs/install/kubernetes.mdx index 8c5284d2ce..22283e9cf9 100644 --- a/docs/docs/install/kubernetes.mdx +++ b/docs/docs/install/kubernetes.mdx @@ -26,28 +26,82 @@ This guide explains how to install a Tracetest Agent in your Kubernetes environm ## Install the Tracetest Agent with Kubernetes -[Tracetest Agent](/concepts/agent) runs as a Kubernetes Daemonset. +[Tracetest Agent](/concepts/agent) runs as a Kubernetes Deployment with a Service. + +```yaml title="tracetest-agent.yaml" +--- +# Service +apiVersion: v1 +kind: Service +metadata: + name: tracetest-agent + labels: + app.kubernetes.io/name: tracetest-agent + app.kubernetes.io/instance: tracetest-agent +spec: + selector: + app.kubernetes.io/name: tracetest-agent + app.kubernetes.io/instance: tracetest-agent + ports: + - name: grpc-collector-entrypoint + protocol: TCP + port: 4317 + targetPort: 4317 + - name: http-collector-entrypoint + protocol: TCP + port: 4318 + targetPort: 4318 +--- +# Deployment +apiVersion: apps/v1 +kind: Deployment +metadata: + name: tracetest-agent + labels: + app: tracetest-agent + app.kubernetes.io/name: tracetest-agent + app.kubernetes.io/instance: tracetest-agent +spec: + selector: + matchLabels: + app.kubernetes.io/name: tracetest-agent + app.kubernetes.io/instance: tracetest-agent + template: + metadata: + labels: + app.kubernetes.io/name: tracetest-agent + app.kubernetes.io/instance: tracetest-agent + spec: + containers: + - name: agent + image: "kubeshop/tracetest-agent:latest" + imagePullPolicy: Always + args: [ + "--environment", + "", # Add your env id + "--api-key", + "$TRACETEST_API_KEY", + "--server-url", + "https://app.tracetest.io", + ] + env: + - name: TRACETEST_API_KEY + value: "" # Add your API key +``` ```bash title="Terminal" -curl https://raw.githubusercontent.com/kubeshop/tracetest/main/k8s/agent/deploy-agent.sh | bash -s -- default --environment +kubectl apply -f ./tracetest-agent.yaml ``` The Tracetest Agent is running in Kubernetes and ready to accept traces. -gRPC: `http://:4317` +gRPC: `http://tracetest-agent.default.svc.cluster.local:4317` -HTTP: `http://:4318/v1/traces` +HTTP: `http://tracetest-agent.default.svc.cluster.local:4318/v1/traces` :::note K8s Network -Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. +Make sure to check use the correct `` if you edit the Tracetest Agent `service` name. -To run tests against apps running on your local machine you have two options: - -1. Run the Tracetest Agent locally with the `tracetest start` command. -2. Add the Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `:8080` in the URL field when creating a test.* - -You can reach services running on your local machine using: - -- Linux (docker version < 20.10.0): `172.17.0.1:8080` -- MacOS (docker version >= 18.03) and Linux (docker version >= 20.10.0): `host.docker.internal:8080` +Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. +Make sure to run tests using the internal Kubernetes service networking eg: `http://api.default.svc.cluster.internal:port`. ::: diff --git a/docs/docs/install/helm.mdx b/docs/docs/install/on-prem-helm.mdx similarity index 94% rename from docs/docs/install/helm.mdx rename to docs/docs/install/on-prem-helm.mdx index 2bbd106f1b..0bd6d525c9 100644 --- a/docs/docs/install/helm.mdx +++ b/docs/docs/install/on-prem-helm.mdx @@ -1,5 +1,5 @@ --- -id: helm +id: on-prem-helm title: Install with Helm hide_table_of_contents: false description: Installation and deployment instructions for using Helm to deploy Enterprise self-hosted Tracetest and use the On-Prem Tracetest Control Plane / Dashboard. @@ -23,12 +23,12 @@ Installation and deployment instructions for using Helm to deploy Enterprise sel ## Install Tracetest On-Premises with Helm -The [main chart for this repository is called `tracetest-onprem`](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md) and contains all components necessary to run Enterprise self-hosted Tracetest on-premises in a cluster that fits the [deployment architecture](/install/deployment-architecture). +The [main chart for this repository is called `tracetest-onprem`](https://github.com/kubeshop/tracetest-cloud-charts/tree/main/charts/tracetest-onprem) and contains all components necessary to run Enterprise self-hosted Tracetest on-premises in a cluster that fits the [deployment architecture](/install/deployment-architecture). -```bash title="Terminal" -helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update +```js title="Terminal" +helm repo add tracetestcloud https://kubeshop.github.io/tracetest-cloud-charts --force-update && \ -helm install my-tracetest tracetestcloud/tracetest-onprem \ +helm install -n tracetestcloud/tracetest-onprem \ --set global.licenseKey= \ --values values.yaml ``` diff --git a/docs/sidebars.js b/docs/sidebars.js index 50a392e955..fadd2da2a9 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -574,6 +574,11 @@ const sidebars = { id: "install/kubernetes", label: "Install with Kubernetes", }, + { + type: "doc", + id: "install/cloud-helm", + label: "Install with Helm", + }, ], }, { @@ -582,7 +587,7 @@ const sidebars = { items: [ { type: "doc", - id: "install/helm", + id: "install/on-prem-helm", label: "Install with Helm", }, { From eb3f09e9632a68e4b6acd62d329e9f28066b0ac3 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Sep 2024 16:35:46 +0200 Subject: [PATCH 3/5] docs(install): edit links and bullets --- docs/docs/getting-started/installation.mdx | 2 +- docs/docs/install/deployment-architecture.mdx | 2 +- docs/docs/install/overview.mdx | 16 +++++++++++++--- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/docs/getting-started/installation.mdx b/docs/docs/getting-started/installation.mdx index d830db4155..e41e0400b7 100644 --- a/docs/docs/getting-started/installation.mdx +++ b/docs/docs/getting-started/installation.mdx @@ -404,7 +404,7 @@ This installation is meant for testing purposes only. It uses self signed certif For the Production-ready installation: - [View the official Helm chart readme](https://github.com/kubeshop/tracetest-cloud-charts/blob/main/README.md). -- [View the official installation docs](/install/helm). +- [View the official installation docs](/install/on-prem-helm). ::: 1. Install [Helm](https://helm.sh/) and [kind](https://kind.sigs.k8s.io/) on your machine. Clone the official Tracetest Helm chart. diff --git a/docs/docs/install/deployment-architecture.mdx b/docs/docs/install/deployment-architecture.mdx index be9728a2f5..a5b183ed57 100644 --- a/docs/docs/install/deployment-architecture.mdx +++ b/docs/docs/install/deployment-architecture.mdx @@ -25,7 +25,7 @@ You can deploy Tracetest in two ways. With Enterprise self-hosted Tracetest you deploy both the control plane and agent in your own infrastructure. -To deploy Enterprise self-hosted Tracetest follow the [installing with Helm guide](/install/helm). +To deploy Enterprise self-hosted Tracetest follow the [installing with Helm guide](/install/on-prem-helm). ## Architecture diff --git a/docs/docs/install/overview.mdx b/docs/docs/install/overview.mdx index 2cc26e55d9..891c8154d6 100644 --- a/docs/docs/install/overview.mdx +++ b/docs/docs/install/overview.mdx @@ -24,9 +24,19 @@ Tracetest supports two deployment models. With both options Tracetest Agents run in your infrastructure on the same network as your application under test. Tracetest Agents are test runners and trace ingestors. You can choose to run the control plane / dashboard self-hosted or let us manage it in Cloud-based managed Tracetest, it's up to you. Check out the [deployment architecture](/install/deployment-architecture) to learn more. -You can install Tracetest by using one of the following deployment options: + +## Cloud-based Managed Tracetest + +You can install Cloud-based Managed Tracetest by using one of the following deployment options. - Use the [Tracetest CLI](/install/cli) for an out-of-the-box experience with Cloud-based managed Tracetest. - Use [Docker](/install/docker) to run Tracetest Agent with with Cloud-based managed Tracetest. -- Use [Kubernetes](/install/kubernetes) to run Tracetest Agent with with Cloud-based managed Tracetest. -- Use the [Tracetest Helm Chart](/install/helm) to customize your deployment with Enterprise self-hosted Tracetest. +- Use [Kubernetes](/install/kubernetes) to run Tracetest Agent with Cloud-based managed Tracetest. +- Use the [Tracetest Helm Chart](/install/cloud-helm) to install Tracetest Agent with Helm in your Kubernetes cluster and run it with Cloud-based managed Tracetest. + +## Enterprise Self-hosted Tracetest + +You can install Enterprise Self-hosted Tracetest by using one of the following deployment options. + +- Use the [Tracetest Helm Chart](/install/on-prem-helm) to customize your deployment with Enterprise self-hosted Tracetest. +- Use the [Tracetest Helm Chart with GCP](/install/gcp) to customize your deployment of Enterprise self-hosted Tracetest for running in GCP. From e8f7812cd8e0354f64447975761004f4b5619da8 Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Sep 2024 16:53:04 +0200 Subject: [PATCH 4/5] docs(cicd): remove core gh actions --- .../github-actions-pipeline.mdx | 507 ------------------ docs/sidebars.js | 5 - docs/vercel.json | 5 + 3 files changed, 5 insertions(+), 512 deletions(-) delete mode 100644 docs/docs/ci-cd-automation/github-actions-pipeline.mdx diff --git a/docs/docs/ci-cd-automation/github-actions-pipeline.mdx b/docs/docs/ci-cd-automation/github-actions-pipeline.mdx deleted file mode 100644 index 4b7ba3f402..0000000000 --- a/docs/docs/ci-cd-automation/github-actions-pipeline.mdx +++ /dev/null @@ -1,507 +0,0 @@ ---- -id: github-actions-pipeline -title: GitHub Actions Pipeline -description: Quick start how to configure GitHub Actions to run Tracetest trace-based tests against a Node.js app with OpenTelemetry instrumentation and traces. -keywords: - - tracetest - - trace-based testing - - observability - - distributed tracing - - testing -image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg ---- - -:::note -[Check out the source code on GitHub here.](https://github.com/kubeshop/tracetest/tree/main/examples/quick-start-github-actions) -::: - -[Tracetest](https://tracetest.io/) is a testing tool based on [OpenTelemetry](https://opentelemetry.io/) that allows you to test your distributed application. It allows you to use data from distributed traces generated by OpenTelemetry to validate and assert if your application has the desired behavior defined by your test definitions. - -## GitHub Actions Workflow for Running Tracetest tests against a sample Node.js app with OpenTelemetry - -This is a simple quick start on how to configure GitHub Actions to run Tracetest tests against a Node.js app thats uses OpenTelemetry instrumentation with traces. This example includes manual instrumentation and a sample bookstore array that simulates fetching data from a database. - -## GitHub Actions Workflow - -This sample has two workflows. The workflows have one job and a total of 6 steps. The steps are: - -1. Checking out the repo code -2. Starting the sample app with Docker Compose -3. Installing the Tracetest CLI -4. Configuring the Tracetest CLI -5. Running tests with the Tracetest CLI -6. Stop Docker Compose - -The first workflow triggers a pre-merge and merge test run. - -```yaml -# start-and-test-on-main.yaml - -name: Docker Compose Start and Test on push and PR to main - -on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - -jobs: - start-and-test: - timeout-minutes: 10 - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v1 - - - name: Start containers - run: docker compose -f "docker-compose.yaml" -f "tracetest/docker-compose.yaml" up -d --build - - - name: Install Tracetest CLI - shell: bash - run: curl -L https://raw.githubusercontent.com/kubeshop/tracetest/main/install-cli.sh | bash - - - name: Configure Tracetest CLI - run: tracetest configure -g --server-url http://localhost:11633 - - - name: Run tests via the Tracetest CLI - run: | - tracetest run test -f ./tracetest/tests/test-api.yaml - tracetest run test -f ./tracetest/tests/test-api-and-av.yaml - tracetest run testsuite -f ./tracetest/tests/testsuite-api.yaml - - - name: Stop containers - if: always() - run: docker compose -f "docker-compose.yaml" -f "tracetest/docker-compose.yaml" down -v -``` - -And, the other is a scheduled test run. - -```yaml -# start-and-test-on-schedule.yaml - -name: Docker Compose Start and Test Every Hour - -on: - schedule: - - cron: '0 * * * *' - -jobs: - start-and-test: - timeout-minutes: 10 - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v1 - - - name: Start containers - run: docker compose -f "docker-compose.yaml" -f "tracetest/docker-compose.yaml" up -d --build - - - name: Install Tracetest CLI - shell: bash - run: curl -L https://raw.githubusercontent.com/kubeshop/tracetest/main/install-cli.sh | bash - - - name: Configure Tracetest CLI - run: tracetest configure -g --server-url http://localhost:11633 - - - name: Run tests via the Tracetest CLI - run: | - tracetest run test -f ./tracetest/tests/test-api.yaml - tracetest run test -f ./tracetest/tests/test-api-and-av.yaml - tracetest run testsuite -f ./tracetest/tests/testsuite-api.yaml - - - name: Stop containers - if: always() - run: docker compose -f "docker-compose.yaml" -f "tracetest/docker-compose.yaml" down -v -``` - -## Project structure - -Let's first explain how the example app is built. It uses Docker Compose, and contains two distinct `docker-compose.yaml` files. As you see in the GitHub Actions Workflow, all services in the example app are started with Docker Compose. - -### 1. Node.js app - -The `docker-compose.yaml` file and `Dockerfile` in the root directory are for the Node.js app. - -### 2. Tracetest - -The `docker-compose.yaml` file, `collector.config.yaml`, `tracetest-provision.yaml`, and `tracetest.config.yaml` in the `tracetest` directory are for the setting up Tracetest and the OpenTelemetry Collector. - -The `tracetest` directory is self-contained and will run all the prerequisites for enabling OpenTelemetry traces and trace-based testing with Tracetest. - -### Docker Compose Network - -All `services` in the `docker-compose.yaml` are on the same network and will be reachable by hostname from within other services. E.g. `tracetest:4317` in the `collector.config.yaml` will map to the `tracetest` service, where the port `4317` is the port where Tracetest accepts traces. - -## Node.js app - -The Node.js app is a simple Express app with two microservices, contained in the `app.js` and `availability.js` files. - -The OpenTelemetry tracing is contained in the `tracing.otel.grpc.js` or `tracing.otel.http.js` files, respectively. -Traces will be sent to the OpenTelemetry Collector. - -Here's the content of the `tracing.otel.grpc.js` file: - -```js -const opentelemetry = require("@opentelemetry/sdk-node"); -const { - getNodeAutoInstrumentations, -} = require("@opentelemetry/auto-instrumentations-node"); -const { - OTLPTraceExporter, -} = require("@opentelemetry/exporter-trace-otlp-grpc"); -const { Resource } = require("@opentelemetry/resources"); -const { - SemanticResourceAttributes, -} = require("@opentelemetry/semantic-conventions"); -const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node"); -const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base"); - -const resource = Resource.default().merge( - new Resource({ - [SemanticResourceAttributes.SERVICE_NAME]: - "quick-start-nodejs-manual-instrumentation", - [SemanticResourceAttributes.SERVICE_VERSION]: "0.0.1", - }) -); - -const provider = new NodeTracerProvider({ resource: resource }); -const exporter = new OTLPTraceExporter({ url: "http://otel-collector:4317" }); -const processor = new BatchSpanProcessor(exporter); -provider.addSpanProcessor(processor); -provider.register(); - -const sdk = new opentelemetry.NodeSDK({ - traceExporter: exporter, - instrumentations: [getNodeAutoInstrumentations()], - serviceName: "quick-start-nodejs-manual-instrumentation", -}); -sdk.start(); -``` - -Depending on which of these you choose, traces will be sent to either the `grpc` or `http` endpoint. - -The hostnames and ports for these are: - -- GRPC: `http://otel-collector:4317` -- HTTP: `http://otel-collector:4318/v1/traces` - -Enabling the tracer is done by preloading the trace file. - -```bash -node -r ./tracing.otel.grpc.js app.js -``` - -In the `package.json` you will see two npm script for running the respective tracers alongside the `app.js`. - -```json -"scripts": { - "app-with-grpc-tracer": "node -r ./tracing.otel.grpc.js app.js", - "app-with-http-tracer": "node -r ./tracing.otel.http.js app.js", - "availability-with-grpc-tracer": "node -r ./tracing.otel.grpc.js availability.js", - "availability-with-http-tracer": "node -r ./tracing.otel.http.js availability.js" -}, -``` - -To start the `app.js` Express server you run this command. - -```bash -npm run app-with-grpc-tracer -# or -npm run app-with-http-tracer -``` - -To start the `availability.js` Express server you run this command. - -```bash -npm run availability-with-grpc-tracer -# or -npm run availability-with-http-tracer -``` - -As you can see the `Dockerfile` does not have a `CMD` section. - -```Dockerfile -FROM node:slim -WORKDIR /usr/src/app -COPY package*.json ./ -RUN npm install -COPY . . -EXPOSE 8080 -``` - -Instead, the `docker-compose.yaml` contains the `CMD` section for both services. - -```yaml -version: "3" -services: - app: - image: quick-start-nodejs - build: . - command: npm run app-with-grpc-tracer - ports: - - "8080:8080" - availability: - image: quick-start-nodejs-availability - build: . - command: npm run availability-with-grpc-tracer - ports: - - "8080" -``` - -To start it, run this command: - -```bash -docker compose build # optional if you haven't already built the image -docker compose up -``` - -This will start the Node.js app. But, you're not sending the traces anywhere. - -Let's fix this by configuring Tracetest and OpenTelemetry Collector. - -## Tracetest - -The `docker-compose.yaml` in the `tracetest` directory is configured with three services. - -- **Postgres** - Postgres is a prerequisite for Tracetest to work. It stores trace data when running the trace-based tests. -- [**OpenTelemetry Collector**](https://opentelemetry.io/docs/collector/) - A vendor-agnostic implementation of how to receive, process and export telemetry data. -- [**Tracetest**](https://tracetest.io/) - Trace-based testing that generates end-to-end tests automatically from traces. - -```yaml -version: "3" -services: - tracetest: - image: kubeshop/tracetest:latest - platform: linux/amd64 - volumes: - - type: bind - source: ./tracetest/tracetest-config.yaml - target: /app/tracetest.yaml - - type: bind - source: ./tracetest/tracetest-provision.yaml - target: /app/provisioning.yaml - ports: - - 11633:11633 - command: --provisioning-file /app/provisioning.yaml - depends_on: - postgres: - condition: service_healthy - otel-collector: - condition: service_started - healthcheck: - test: ["CMD", "wget", "--spider", "localhost:11633"] - interval: 1s - timeout: 3s - retries: 60 - environment: - TRACETEST_DEV: ${TRACETEST_DEV} - - postgres: - image: postgres:14 - environment: - POSTGRES_PASSWORD: postgres - POSTGRES_USER: postgres - healthcheck: - test: pg_isready -U "$$POSTGRES_USER" -d "$$POSTGRES_DB" - interval: 1s - timeout: 5s - retries: 60 - - otel-collector: - image: otel/opentelemetry-collector-contrib:0.59.0 - command: - - "--config" - - "/otel-local-config.yaml" - volumes: - - ./tracetest/collector.config.yaml:/otel-local-config.yaml -``` - -Tracetest depends on both Postgres and the OpenTelemetry Collector. Both Tracetest and the OpenTelemetry Collector require config files to be loaded via a volume. The volumes are mapped from the root directory into the `tracetest` directory and the respective config files. - -The `tracetest-config.yaml` file contains the basic setup of connecting Tracetest to the Postgres instance. - -```yaml -postgres: - host: postgres - user: postgres - password: postgres - port: 5432 - dbname: postgres - params: sslmode=disable -``` - -The `tracetest-provision.yaml` file provisions the trace data store and polling to store in the Postgres database. The data store is set to OTLP meaning the traces will be stored in Tracetest itself. - -```yaml ---- -type: PollingProfile -spec: - name: Default - strategy: periodic - default: true - periodic: - retryDelay: 5s - timeout: 10m - ---- -type: DataStore -spec: - name: OpenTelemetry Collector - type: otlp - default: true -``` - -But how are traces sent to Tracetest? - -The `collector.config.yaml` explains that. It receives traces via either `grpc` or `http`. Then, exports them to Tracetest's otlp endpoint `tracetest:4317`. - -```yaml -receivers: - otlp: - protocols: - grpc: - http: - -processors: - batch: - timeout: 100ms - -exporters: - logging: - loglevel: debug - otlp/1: - endpoint: tracetest:4317 - # Send traces to Tracetest. - # Read more in docs here: https://docs.tracetest.io/configuration/connecting-to-data-stores/opentelemetry-collector - tls: - insecure: true - -service: - pipelines: - traces/1: - receivers: [otlp] - processors: [batch] - exporters: [otlp/1] -``` - -## Run both the Node.js app and Tracetest - -To start both the Node.js services and Tracetest we will run this command: - -```bash -docker-compose -f docker-compose.yaml -f tracetest/docker-compose.yaml up # add --build if the images are not built already -``` - -This will start your Tracetest instance on `http://localhost:11633/`. - -## Run Tracetest tests with the Tracetest CLI - -First, [install the CLI](https://docs.tracetest.io/getting-started/installation#install-the-tracetest-cli). -Then, configure the CLI: - -```bash -tracetest configure --server-url http://localhost:11633 -``` - -Once configured, you can run a test against the Tracetest instance via the terminal. - -Check out the `test-api.yaml` file in the `./tracetest/tests` directory. - -```yaml -type: Test -spec: - id: W656Q0c4g - name: Books List - description: List of books - trigger: - type: http - httpRequest: - url: http://app:8080/books - method: GET - headers: - - key: Content-Type - value: application/json - specs: - - selector: span[tracetest.span.type="http" name="GET /books" http.target="/books" http.method="GET"] - assertions: - - attr:http.status_code = 200 - - selector: span[tracetest.span.type="general" name="Books List"] - assertions: - - attr:books.list.count = 4 -``` - -To run the test, run this command in the terminal: - -```bash -tracetest run test -f ./tracetest/tests/test-api.yaml -``` - -This test will fail just like the sample above due to the `attr:books.list.count = 4` assertion. - -``` -✘ http://app:8080 (http://localhost:11633/test/W656Q0c4g/run/5/test) - ✔ span[tracetest.span.type="http" name="GET /books" http.target="/books" http.method="GET"] - ✔ #994c63e0ea35e632 - ✔ attr:http.status_code = 200 (200) - ✘ span[tracetest.span.type="general" name="Books List"] - ✘ #5ab1856c32b0d5c8 - ✘ attr:books.list.count = 4 (3) (http://localhost:11633/test/W656Q0c4g/run/5/test?selectedAssertion=1&selectedSpan=5ab1856c32b0d5c8) -``` - -The tests will pass if you change the assertion to: - -```css -attr: books.list.count = 3; -``` - -There are two more files in the `./tracetest/tests` directory that we use in the GitHub Actions Workflow. - -The test `test-api-and-av.yaml` also includes assertions for the `availability` service. - -```yaml -# ./tracetest/tests/test-api-and-av.yaml - -type: Test -spec: - id: phAZcrT4B - name: Books list with availability - description: Testing the books list and availability check - trigger: - type: http - httpRequest: - url: http://app:8080/books - method: GET - headers: - - key: Content-Type - value: application/json - specs: - - selector: span[tracetest.span.type="http" name="GET /books" http.target="/books" - http.method="GET"] - assertions: - - attr:tracetest.span.duration < 500ms - - selector: span[tracetest.span.type="general" name="Books List"] - assertions: - - attr:books.list.count = 3 - - selector: span[tracetest.span.type="http" name="GET /availability/:bookId" http.method="GET"] - assertions: - - attr:http.host = "availability:8080" - - selector: span[tracetest.span.type="general" name="Availablity check"] - assertions: - - attr:isAvailable = "true" -``` - -The testsuite `testsuite-api.yaml` will run both the tests above. - -```yaml -# ./tracetest/tests/testsuite-api.yaml - -type: TestSuite -spec: - id: 3YIB7rPVg - name: All Tests for the Books List API - steps: - - phAZcrT4W - - phAZcrT4B -``` - -Feel free to check out our [docs](https://docs.tracetest.io/), and join our [Slack Community](https://dub.sh/tracetest-community) for more info! diff --git a/docs/sidebars.js b/docs/sidebars.js index fadd2da2a9..f1947f796b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -386,11 +386,6 @@ const sidebars = { id: "ci-cd-automation/overview", }, items: [ - { - type: "doc", - id: "ci-cd-automation/github-actions-pipeline", - label: "GitHub Actions Pipeline", - }, { type: "doc", id: "ci-cd-automation/github-actions-pipeline-with-secrets", diff --git a/docs/vercel.json b/docs/vercel.json index 8946dd4caf..c1e1d9678f 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -185,6 +185,11 @@ "destination": "/getting-started/installation", "source": "/deployment/overview", "statusCode": 301 + }, + { + "destination": "/ci-cd-automation/github-actions-pipeline-with-secrets", + "source": "/ci-cd-automation/github-actions-pipeline", + "statusCode": 301 } ] } From 12046c91e22a7d41631af4555aae4defc5cd164c Mon Sep 17 00:00:00 2001 From: Adnan Rahic Date: Tue, 3 Sep 2024 16:55:28 +0200 Subject: [PATCH 5/5] docs(cicd): fix links --- docs/docs/ci-cd-automation/overview.mdx | 1 - docs/docs/examples-tutorials/recipes.mdx | 1 - examples/quick-start-github-actions/readme.md | 2 +- 3 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/docs/ci-cd-automation/overview.mdx b/docs/docs/ci-cd-automation/overview.mdx index 99d713472d..ebdc45501e 100644 --- a/docs/docs/ci-cd-automation/overview.mdx +++ b/docs/docs/ci-cd-automation/overview.mdx @@ -15,7 +15,6 @@ This section contains a general overview of running Tracetest in CI/CD pipelines You can find guides for: -- [GitHub Actions](/ci-cd-automation/github-actions-pipeline) - [GitHub Actions with Secrets](/ci-cd-automation/github-actions-pipeline-with-secrets) - [Testkube](/ci-cd-automation/testkube-pipeline) - [Tekton](/ci-cd-automation/tekton-pipeline) diff --git a/docs/docs/examples-tutorials/recipes.mdx b/docs/docs/examples-tutorials/recipes.mdx index e61a389cf1..ba7ad5df47 100644 --- a/docs/docs/examples-tutorials/recipes.mdx +++ b/docs/docs/examples-tutorials/recipes.mdx @@ -145,7 +145,6 @@ This integration point uses the OpenTelemetry Collector as a router to send trac These guides show integrations with CI/CD tools. -- [GitHub Actions](/ci-cd-automation/github-actions-pipeline) - [GitHub Actions with Secrets](/ci-cd-automation/github-actions-pipeline-with-secrets) - [Testkube](/ci-cd-automation/testkube-pipeline) - [Tekton](/ci-cd-automation/tekton-pipeline) diff --git a/examples/quick-start-github-actions/readme.md b/examples/quick-start-github-actions/readme.md index ed7bcd1ab9..904e069295 100644 --- a/examples/quick-start-github-actions/readme.md +++ b/examples/quick-start-github-actions/readme.md @@ -1,6 +1,6 @@ # GitHub Actions Sample for a Node.js app with OpenTelemetry and Tracetest -> [Read the detailed recipe for setting up GitHub Actions with Tractest in our documentation.](https://docs.tracetest.io/ci-cd-automation/github-actions-pipeline) +> [Read the detailed recipe for setting up GitHub Actions with Tractest in our documentation.](https://docs.tracetest.io/ci-cd-automation/github-actions-pipeline-with-secrets) This is a simple quick start on how to configure GitHub Actions to run Tracetest against a Node.js app that uses OpenTelemetry instrumentation with traces, to enhance your e2e and integration tests with trace-based testing.