From f9cb26fb4a288f536ab20ab3f472060dd465ef56 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 27 Feb 2023 10:09:56 -0500 Subject: [PATCH] Enable Prettier check over demo docs (#2408) --- .prettierignore | 1 - content/en/docs/demo/_index.md | 29 ++-- content/en/docs/demo/architecture.md | 16 +-- content/en/docs/demo/development.md | 6 +- content/en/docs/demo/docker-deployment.md | 20 +-- content/en/docs/demo/feature-flags.md | 6 +- content/en/docs/demo/features.md | 19 +-- content/en/docs/demo/kubernetes-deployment.md | 72 +++++----- .../en/docs/demo/manual-span-attributes.md | 37 ++--- content/en/docs/demo/requirements/_index.md | 9 +- .../en/docs/demo/requirements/application.md | 17 +-- .../en/docs/demo/requirements/architecture.md | 54 ++++---- content/en/docs/demo/requirements/system.md | 4 +- content/en/docs/demo/screenshots.md | 51 +++++-- content/en/docs/demo/services/accounting.md | 9 +- content/en/docs/demo/services/ad.md | 25 ++-- content/en/docs/demo/services/cart.md | 17 ++- content/en/docs/demo/services/checkout.md | 8 +- content/en/docs/demo/services/currency.md | 4 +- content/en/docs/demo/services/email.md | 12 +- content/en/docs/demo/services/feature-flag.md | 8 +- .../en/docs/demo/services/fraud-detection.md | 4 +- .../en/docs/demo/services/frontend-proxy.md | 19 ++- content/en/docs/demo/services/frontend.md | 130 +++++++++++------- content/en/docs/demo/services/kafka.md | 11 +- .../en/docs/demo/services/load-generator.md | 13 +- content/en/docs/demo/services/payment.md | 92 ++++++++----- .../en/docs/demo/services/product-catalog.md | 10 +- content/en/docs/demo/services/quote.md | 32 +++-- .../en/docs/demo/services/recommendation.md | 22 +-- content/en/docs/demo/services/shipping.md | 50 +++---- content/en/docs/demo/tests.md | 8 +- 32 files changed, 442 insertions(+), 373 deletions(-) diff --git a/.prettierignore b/.prettierignore index 186340fcdf1..06f38d71097 100644 --- a/.prettierignore +++ b/.prettierignore @@ -25,7 +25,6 @@ package-lock.json /assets/**/*.js /content/en/blog/2019 /content/en/blog/2021 -/content/en/docs/demo /data /resources /scripts diff --git a/content/en/docs/demo/_index.md b/content/en/docs/demo/_index.md index 1a6d97e536d..95e1a5e0b35 100644 --- a/content/en/docs/demo/_index.md +++ b/content/en/docs/demo/_index.md @@ -21,19 +21,19 @@ Want to deploy the demo and see it in action? Start here. Want to understand how a particular language's instrumentation works? Start here. -| Language | Auto Instrumentation | Manual Instrumentation | -|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| -| .NET | [Cart Service](services/cart/) | [Cart Service](services/cart/) | -| C++ | | [Currency Service](services/currency/) | -| Erlang/Elixir | [Feature Flag Service](services/feature-flag/) | [Feature Flag Service](services/feature-flag/) | -| Go | [Accounting Service](services/accounting/), [Checkout Service](services/checkout/), [Product Catalog Service]( services/product-catalog/ ) | [Checkout Service](services/checkout/), [Product Catalog Service]( services/product-catalog/ ) | -| Java | [Ad Service](services/ad/) | [Ad Service](services/ad/) | -| JavaScript | [Frontend]( services/frontend/ ) | [Frontend](services/frontend/), [Payment Service](services/payment/) | -| Kotlin | [Fraud Detection Service]( services/fraud-detection/ ) | | -| PHP | [Quote Service](services/quote/) | [Quote Service](services/quote/) | -| Python | [Recommendation Service](services/recommendation/) | [Recommendation Service](services/recommendation/) | -| Ruby | [Email Service](services/email/) | [Email Service](services/email/) | -| Rust | [Shipping Service](services/shipping/) | [Shipping Service](services/shipping/) | +| Language | Auto Instrumentation | Manual Instrumentation | +| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| .NET | [Cart Service](services/cart/) | [Cart Service](services/cart/) | +| C++ | | [Currency Service](services/currency/) | +| Erlang/Elixir | [Feature Flag Service](services/feature-flag/) | [Feature Flag Service](services/feature-flag/) | +| Go | [Accounting Service](services/accounting/), [Checkout Service](services/checkout/), [Product Catalog Service](services/product-catalog/) | [Checkout Service](services/checkout/), [Product Catalog Service](services/product-catalog/) | +| Java | [Ad Service](services/ad/) | [Ad Service](services/ad/) | +| JavaScript | [Frontend](services/frontend/) | [Frontend](services/frontend/), [Payment Service](services/payment/) | +| Kotlin | [Fraud Detection Service](services/fraud-detection/) | | +| PHP | [Quote Service](services/quote/) | [Quote Service](services/quote/) | +| Python | [Recommendation Service](services/recommendation/) | [Recommendation Service](services/recommendation/) | +| Ruby | [Email Service](services/email/) | [Email Service](services/email/) | +| Rust | [Shipping Service](services/shipping/) | [Shipping Service](services/shipping/) | ## Service Documentation @@ -63,7 +63,8 @@ We'll be adding more scenarios over time. - Generate a [Product Catalog error](feature-flags) for `GetProduct` requests with product id: `OLJCESPC7Z` using the Feature Flag service -- Discover a memory leak and diagnose it using metrics and traces. [Read more](scenarios/recommendation-cache/) +- Discover a memory leak and diagnose it using metrics and traces. + [Read more](scenarios/recommendation-cache/) ## Reference diff --git a/content/en/docs/demo/architecture.md b/content/en/docs/demo/architecture.md index 691d4551db0..9a3c97f023b 100644 --- a/content/en/docs/demo/architecture.md +++ b/content/en/docs/demo/architecture.md @@ -4,9 +4,9 @@ linkTitle: Architecture aliases: [/docs/demo/current_architecture] --- -**OpenTelemetry Demo** is composed of microservices written in different programming -languages that talk to each other over gRPC and HTTP; and a load generator which -uses [Locust](https://locust.io/) to fake user traffic. +**OpenTelemetry Demo** is composed of microservices written in different +programming languages that talk to each other over gRPC and HTTP; and a load +generator which uses [Locust](https://locust.io/) to fake user traffic. ```mermaid graph TD @@ -114,14 +114,12 @@ classDef typescript fill:#e98516,color:black; ``` Follow these links for the current state of - [metric](/docs/demo/metric-features/) - and - [trace](/docs/demo/trace-features/) - instrumentation of the demo applications. +[metric](/docs/demo/metric-features/) and [trace](/docs/demo/trace-features/) +instrumentation of the demo applications. The collector is configured in - [otelcol-config.yml](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/otelcollector/otelcol-config.yml), - alternative exporters can be configured here. +[otelcol-config.yml](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/otelcollector/otelcol-config.yml), +alternative exporters can be configured here. ```mermaid graph TB diff --git a/content/en/docs/demo/development.md b/content/en/docs/demo/development.md index 8a943757d8d..d21620f2fd0 100644 --- a/content/en/docs/demo/development.md +++ b/content/en/docs/demo/development.md @@ -3,9 +3,9 @@ title: Development --- Development for this demo requires tooling in several programming languages. -Minimum required versions will be noted where possible, but it is recommended -to update to the latest version for all tooling. The OpenTelemetry demo team -will attempt to keep the services in this repository up to date with the latest +Minimum required versions will be noted where possible, but it is recommended to +update to the latest version for all tooling. The OpenTelemetry demo team will +attempt to keep the services in this repository up to date with the latest version for dependencies and tooling when possible. ## Generate Protobuf files diff --git a/content/en/docs/demo/docker-deployment.md b/content/en/docs/demo/docker-deployment.md index cc254040503..d9e4c9ff9b3 100644 --- a/content/en/docs/demo/docker-deployment.md +++ b/content/en/docs/demo/docker-deployment.md @@ -7,7 +7,8 @@ aliases: [/docs/demo/docker_deployment] ## Prerequisites - Docker -- [Docker Compose](https://docs.docker.com/compose/install/#install-compose) v2.0.0+ +- [Docker Compose](https://docs.docker.com/compose/install/#install-compose) + v2.0.0+ - 5 GB of RAM ## Clone Repo @@ -34,8 +35,9 @@ cd opentelemetry-demo/ docker compose up --no-build ``` -> **Note:** If you're running on Apple Silicon, please run `docker compose -> build` in order to create local images vs. pulling them from the repository. +> **Note:** If you're running on Apple Silicon, please run +> `docker compose build` in order to create local images vs. pulling them from +> the repository. **Note:** The `--no-build` flag is used to fetch released docker images from [ghcr](https://ghcr.io/open-telemetry/demo) instead of building from source. @@ -55,8 +57,8 @@ Once the images are built and containers are started you can access: ## Bring your own backend Likely you want to use the Webstore as a demo application for an observability -backend you already have (e.g. an existing instance of Jaeger, Zipkin, or one -of the [vendor of your choice](/ecosystem/vendors/). +backend you already have (e.g. an existing instance of Jaeger, Zipkin, or one of +the [vendor of your choice](/ecosystem/vendors/). OpenTelemetry Collector can be used to export telemetry data to multiple backends. By default, the collector in the demo application will merge the @@ -69,8 +71,8 @@ To add your backend, open the file [src/otelcollector/otelcol-config-extras.yml](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/otelcollector/otelcol-config-extras.yml) with an editor. -- Start by adding a new exporter. For example, if your backend supports - OTLP over HTTP, add the following: +- Start by adding a new exporter. For example, if your backend supports OTLP + over HTTP, add the following: ```yaml exporters: @@ -95,5 +97,5 @@ different exporters, you may find them and their documentation available at [opentelemetry-collector-contrib/exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter). After updating the `otelcol-config-extras.yml`, start the demo by running -`docker compose up`. After a while, you should see the traces flowing into -your backend as well. +`docker compose up`. After a while, you should see the traces flowing into your +backend as well. diff --git a/content/en/docs/demo/feature-flags.md b/content/en/docs/demo/feature-flags.md index 5936dd5e5fa..03c0cb96840 100644 --- a/content/en/docs/demo/feature-flags.md +++ b/content/en/docs/demo/feature-flags.md @@ -5,11 +5,11 @@ aliases: [/docs/demo/feature_flags] This demo comes with several feature flags which can control failure conditions in specific services. By default the flags are disabled. Using the Feature Flags -UI you will be able to control the status of these -feature flags. +UI you will be able to control the status of +these feature flags. | Feature Flag | Service(s) | Description | -|-------------------------|-----------------|----------------------------------------------------------------------------------------------------------| +| ----------------------- | --------------- | -------------------------------------------------------------------------------------------------------- | | `adServiceFailure` | Ad Service | Generate an error for `GetAds` 1/10th of the time | | `productCatalogFailure` | Product Catalog | Generate an error for `GetProduct` requests with product id: `OLJCESPC7Z` | | `recommendationCache` | Recommendation | Create a memory leak due to an exponentially growing cache. 1.4x growth, 50% of requests trigger growth. | diff --git a/content/en/docs/demo/features.md b/content/en/docs/demo/features.md index ed1becda0aa..d81330eec40 100644 --- a/content/en/docs/demo/features.md +++ b/content/en/docs/demo/features.md @@ -10,18 +10,18 @@ aliases: [/docs/demo/demo_features] only with Docker. - **[gRPC](https://grpc.io)**: microservices use a high volume of gRPC calls to communicate to each other. -- **[HTTP](https://www.rfc-editor.org/rfc/rfc9110.html)**: microservices use HTTP - where gRPC is unavailable or not well supported. +- **[HTTP](https://www.rfc-editor.org/rfc/rfc9110.html)**: microservices use + HTTP where gRPC is unavailable or not well supported. - **[OpenTelemetry Traces](https://opentelemetry.io)**: all services are instrumented using OpenTelemetry available instrumentation libraries. - **[OpenTelemetry Metrics](https://opentelemetry.io)**: Select services are -instrumented using OpenTelemetry available instrumentation libraries. More will -be added as the relevant SDKs are released. -- **[OpenTelemetry - Collector](/docs/collector/getting-started)**: all - services are instrumented and sending the generated traces and metrics to the + instrumented using OpenTelemetry available instrumentation libraries. More + will be added as the relevant SDKs are released. +- **[OpenTelemetry Collector](/docs/collector/getting-started)**: all services + are instrumented and sending the generated traces and metrics to the OpenTelemetry Collector via gRPC. The received traces are then exported to the - logs and to Jaeger; received metrics and exemplars* are exported to logs and Prometheus. + logs and to Jaeger; received metrics and exemplars\* are exported to logs and + Prometheus. - **[Jaeger](https://www.jaegertracing.io)**: all generated traces are being sent to Jaeger. - **Synthetic Load Generation**: the application demo comes with a background @@ -36,5 +36,6 @@ be added as the relevant SDKs are released. flag service. _\*Only exemplars attached to histograms are currently exported to Prometheus. -See [issue in the collector](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/18201) +See +[issue in the collector](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/18201) for details._ diff --git a/content/en/docs/demo/kubernetes-deployment.md b/content/en/docs/demo/kubernetes-deployment.md index 1f05dbb5217..a62c73eae2a 100644 --- a/content/en/docs/demo/kubernetes-deployment.md +++ b/content/en/docs/demo/kubernetes-deployment.md @@ -4,12 +4,12 @@ linkTitle: Kubernetes aliases: [/docs/demo/kubernetes_deployment] --- -We provide a [OpenTelemetry Demo Helm -chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-demo) +We provide a +[OpenTelemetry Demo Helm chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-demo) to help deploy the demo to an existing Kubernetes cluster. -[Helm](https://helm.sh) must be installed to use the charts. -Please refer to Helm's [documentation](https://helm.sh/docs/) to get started. +[Helm](https://helm.sh) must be installed to use the charts. Please refer to +Helm's [documentation](https://helm.sh/docs/) to get started. ## Prerequisites @@ -24,22 +24,22 @@ Add OpenTelemetry Helm repository: helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts ``` -To install the chart with the release name my-otel-demo, run the following command: +To install the chart with the release name my-otel-demo, run the following +command: ```shell helm install my-otel-demo open-telemetry/opentelemetry-demo ``` -> **Note** -> The OpenTelemetry Demo Helm chart version 0.11.0 or greater is required to -> perform all usage methods mentioned below. +> **Note** The OpenTelemetry Demo Helm chart version 0.11.0 or greater is +> required to perform all usage methods mentioned below. ## Use the Demo The demo application will need the services exposed outside of the Kubernetes cluster in order to use them. You can expose the services to your local system -using the `kubectl port-forward` command or by configuring service types -(ie: LoadBalancer) with optionally deployed ingress resources. +using the `kubectl port-forward` command or by configuring service types (ie: +LoadBalancer) with optionally deployed ingress resources. ### Expose services using kubectl port-forward @@ -50,17 +50,16 @@ To expose the frontendproxy service use the following command (replace kubectl port-forward svc/my-otel-demo-frontendproxy 8080:8080 ``` -In order for spans from the browser to be properly collected, you will also -need to expose the OpenTelemetry Collector's OTLP/HTTP port (replace -`my-otel-demo` with your Helm chart release name accordingly): +In order for spans from the browser to be properly collected, you will also need +to expose the OpenTelemetry Collector's OTLP/HTTP port (replace `my-otel-demo` +with your Helm chart release name accordingly): ```shell kubectl port-forward svc/my-otel-demo-otelcol 4318:4318 ``` -> **Note** -> `kubectl port-forward` will proxy the port until the process terminates. You -> may need to create separate terminal sessions for each use of +> **Note** > `kubectl port-forward` will proxy the port until the process +> terminates. You may need to create separate terminal sessions for each use of > `kubectl port-forward`, and use CTRL-C to terminate the process when done. With the frontendproxy and Collector port-forward set up, you can access: @@ -73,9 +72,8 @@ With the frontendproxy and Collector port-forward set up, you can access: ### Expose services using service type configurations -> **Note** -> Kubernetes clusters may not have the proper infrastructure components to -> enable LoadBalancer service types or ingress resources. Verify your cluster +> **Note** Kubernetes clusters may not have the proper infrastructure components +> to enable LoadBalancer service types or ingress resources. Verify your cluster > has the proper support before using these configuration options. Each demo service (ie: frontendproxy) offers a way to have its Kubernetes @@ -92,19 +90,19 @@ components: type: LoadBalancer ``` -> **Note** -> It is recommended to use a values file when installing the Helm chart in order -> to specify additional configuration options. +> **Note** It is recommended to use a values file when installing the Helm chart +> in order to specify additional configuration options. The Helm chart does not provide facilities to create ingress resources. If -required these would need to be created manually after installing the Helm chart. -Some Kubernetes providers require specific service types in order to be used by -ingress resources (ie: EKS ALB ingress, requires a NodePort service type). - -In order for spans from the browser to be properly collected, you will also -need to expose the OpenTelemetry Collector's OTLP/HTTP port to be accessible to -user web browsers. The location where the OpenTelemetry Collector is exposed -must also be passed into the frontend service using the +required these would need to be created manually after installing the Helm +chart. Some Kubernetes providers require specific service types in order to be +used by ingress resources (ie: EKS ALB ingress, requires a NodePort service +type). + +In order for spans from the browser to be properly collected, you will also need +to expose the OpenTelemetry Collector's OTLP/HTTP port to be accessible to user +web browsers. The location where the OpenTelemetry Collector is exposed must +also be passed into the frontend service using the `PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable. You can do this using the following in your values file: @@ -113,7 +111,7 @@ components: frontend: env: - name: PUBLIC_OTEL_EXPORTER_OTLP_TRACES_ENDPOINT - value: "http://otel-demo-collector.mydomain.com:4318/v1/traces" + value: http://otel-demo-collector.mydomain.com:4318/v1/traces ``` To install the Helm chart with a custom `my-values-file.yaml` values file use: @@ -135,12 +133,12 @@ following sub-paths: ## Bring your own backend Likely you want to use the Webstore as a demo application for an observability -backend you already have (e.g. an existing instance of Jaeger, Zipkin, or one -of the [vendor of your choice](/ecosystem/vendors/). +backend you already have (e.g. an existing instance of Jaeger, Zipkin, or one of +the [vendor of your choice](/ecosystem/vendors/). The OpenTelemetry Collector's configuration is exposed in the Helm chart. Any -additions you do will be merged into the default configuration. You can use -this to add your own exporters, and add them to the desired pipeline(s) +additions you do will be merged into the default configuration. You can use this +to add your own exporters, and add them to the desired pipeline(s) ```yaml opentelemetry-collector: @@ -157,8 +155,8 @@ opentelemetry-collector: exporters: [otlphttp/example] ``` -> **Note** -> When merging YAML values with Helm, objects are merged and arrays are replaced. +> **Note** When merging YAML values with Helm, objects are merged and arrays are +> replaced. Vendor backends might require you to add additional parameters for authentication, please check their documentation. Some backends require diff --git a/content/en/docs/demo/manual-span-attributes.md b/content/en/docs/demo/manual-span-attributes.md index ba1ac296385..bf2e9bd32ac 100644 --- a/content/en/docs/demo/manual-span-attributes.md +++ b/content/en/docs/demo/manual-span-attributes.md @@ -3,12 +3,13 @@ title: Manual Span Attributes aliases: [/docs/demo/manual_span_attributes] --- -This document contains the list of manual Span Attributes used throughout the demo: +This document contains the list of manual Span Attributes used throughout the +demo: ## AdService | Name | Type | Description | -|-----------------------------|--------|---------------------------------------| +| --------------------------- | ------ | ------------------------------------- | | `app.ads.category` | string | Category for returned ad | | `app.ads.contextKeys` | string | Context keys used to find related ads | | `app.ads.contextKeys.count` | number | Count of unique context keys used | @@ -19,7 +20,7 @@ This document contains the list of manual Span Attributes used throughout the de ## CartService | Name | Type | Description | -|------------------------|--------|--------------------------------| +| ---------------------- | ------ | ------------------------------ | | `app.cart.items.count` | number | Number of unique items in cart | | `app.product.id` | string | Product Id for cart item | | `app.product.quantity` | string | Quantity for cart item | @@ -28,7 +29,7 @@ This document contains the list of manual Span Attributes used throughout the de ## CheckoutService | Name | Type | Description | -|------------------------------|--------|---------------------------------| +| ---------------------------- | ------ | ------------------------------- | | `app.cart.items.count` | number | Total number of items in cart | | `app.order.amount` | number | Order amount | | `app.order.id` | string | Order Id | @@ -42,29 +43,29 @@ This document contains the list of manual Span Attributes used throughout the de ## CurrencyService | Name | Type | Description | -|--------------------------------|--------|-------------------------------| +| ------------------------------ | ------ | ----------------------------- | | `app.currency.conversion.from` | string | Currency code to convert from | | `app.currency.conversion.to` | string | Currency code to convert to | ## EmailService | Name | Type | Description | -|-----------------------|--------|-----------------------------------| +| --------------------- | ------ | --------------------------------- | | `app.email.recipient` | string | Email used for order confirmation | | `app.order.id` | string | Order Id | ## FeatureFlagService -| Name | Type | Description | -|-------------------------------|--------|--------------------------| -| `app.featureflag.name` | string | Name of the feature flag | -| `app.featureflag.description` | string | Admin description | -| `app.featureflag.enabled` | boolean | The feature flag status | +| Name | Type | Description | +| ----------------------------- | ------- | ------------------------ | +| `app.featureflag.name` | string | Name of the feature flag | +| `app.featureflag.description` | string | Admin description | +| `app.featureflag.enabled` | boolean | The feature flag status | ## Frontend | Name | Type | Description | -|--------------------------|--------|-------------------------------| +| ------------------------ | ------ | ----------------------------- | | `app.cart.size` | number | Total number of items in cart | | `app.cart.items.count` | number | Count of unique items in cart | | `app.cart.shipping.cost` | number | Cart shipping cost | @@ -82,13 +83,13 @@ This document contains the list of manual Span Attributes used throughout the de ## LoadGenerator | Name | Type | Description | -|----------|------|-------------| +| -------- | ---- | ----------- | | None yet | | | ## PaymentService | Name | Type | Description | -|--------------------------|---------|------------------------------------------------------| +| ------------------------ | ------- | ---------------------------------------------------- | | `app.payment.amount` | number | Total payment amount | | `app.payment.card_type` | string | Type of card used for payment | | `app.payment.card_valid` | boolean | Was the card used valid | @@ -97,7 +98,7 @@ This document contains the list of manual Span Attributes used throughout the de ## ProductCatalogService | Name | Type | Description | -|-----------------------------|--------|---------------------------------------| +| --------------------------- | ------ | ------------------------------------- | | `app.product.id` | string | Product Id | | `app.product.name` | string | Product name | | `app.products.count` | number | Number of products in catalog | @@ -106,14 +107,14 @@ This document contains the list of manual Span Attributes used throughout the de ## QuoteService | Name | Type | Description | -|-------------------------|--------|----------------------| +| ----------------------- | ------ | -------------------- | | `app.quote.items.count` | number | Total items to ship | | `app.quote.cost.total` | number | Total shipping quote | ## RecommendationService | Name | Type | Description | -|----------------------------------|---------|-----------------------------------------| +| -------------------------------- | ------- | --------------------------------------- | | `app.filtered_products.count` | number | Number of filtered products returned | | `app.products.count` | number | Number of products in catalog | | `app.products_recommended.count` | number | Number of recommended products returned | @@ -122,7 +123,7 @@ This document contains the list of manual Span Attributes used throughout the de ## ShippingService | Name | Type | Description | -|----------------------------|--------|-------------------------------| +| -------------------------- | ------ | ----------------------------- | | `app.shipping.cost.total` | number | Total shipping cost | | `app.shipping.items.count` | number | Total items to ship | | `app.shipping.tracking.id` | string | Shipping tracking Id | diff --git a/content/en/docs/demo/requirements/_index.md b/content/en/docs/demo/requirements/_index.md index a2f8740d1ac..3d361e41ddf 100644 --- a/content/en/docs/demo/requirements/_index.md +++ b/content/en/docs/demo/requirements/_index.md @@ -3,9 +3,9 @@ title: Demo Requirements linkTitle: Requirements --- -The following documents capture the Application, OpenTelemetry (OTel), and System -requirements for our shared demo application. These were decided upon in the -ongoing SIG meeting. +The following documents capture the Application, OpenTelemetry (OTel), and +System requirements for our shared demo application. These were decided upon in +the ongoing SIG meeting. 1. [Application Requirements](application/) 2. [OpenTelemetry Requirements](opentelemetry/) @@ -13,7 +13,8 @@ ongoing SIG meeting. ## Target Personas -We're building the demo application with several different target personas in mind: +We're building the demo application with several different target personas in +mind: 1. **Enthusiasts** at a company that can use the demo app as an individual to advocate for OTel within their organization. diff --git a/content/en/docs/demo/requirements/application.md b/content/en/docs/demo/requirements/application.md index 9e621a608f2..65ce29cf984 100644 --- a/content/en/docs/demo/requirements/application.md +++ b/content/en/docs/demo/requirements/application.md @@ -11,22 +11,23 @@ added: 1. Every supported language that has a GA Traces or Metrics SDK must have at least 1 service example. - * Mobile support (Swift) is not an initial priority and not included in the - above requirement. + - Mobile support (Swift) is not an initial priority and not included in the + above requirement. 2. Application processes must be language independent. - * gRPC is preferred where available and HTTP is to be used where it is not. + - gRPC is preferred where available and HTTP is to be used where it is not. -3. Services should be architected to be modular components that can be switched out. +3. Services should be architected to be modular components that can be switched + out. - * Individual services can and should be encouraged to have multiple language - options available. + - Individual services can and should be encouraged to have multiple language + options available. 4. The architecture must allow for the possible integration of platform generic components like a database, queue, or blob storage. - * There is no requirement for a particular component type - at least 1 generic - component should be present in general. + - There is no requirement for a particular component type - at least 1 + generic component should be present in general. 5. A load generator must be provided to simulate user load against the demo. diff --git a/content/en/docs/demo/requirements/architecture.md b/content/en/docs/demo/requirements/architecture.md index 8a0045e5150..1f2f434ce11 100644 --- a/content/en/docs/demo/requirements/architecture.md +++ b/content/en/docs/demo/requirements/architecture.md @@ -7,10 +7,10 @@ aliases: [/docs/demo/requirements/architecture_requirements] ## Summary The OpenTelemetry Community Demo application is intended to be a 'showcase' for -OpenTelemetry API, SDK, and tools in a production-lite cloud native -application. The overall goal of this application is not only to provide a -canonical 'demo' of OpenTelemetry components, but also to act as a framework for -further customization by end-users, vendors, and other stakeholders. +OpenTelemetry API, SDK, and tools in a production-lite cloud native application. +The overall goal of this application is not only to provide a canonical 'demo' +of OpenTelemetry components, but also to act as a framework for further +customization by end-users, vendors, and other stakeholders. ### Requirements @@ -21,25 +21,23 @@ further customization by end-users, vendors, and other stakeholders. ### Application Goals - Provide developers with a robust sample application they can use in learning -OpenTelemetry instrumentation. -- Provide observability vendors with a single, -well-supported, demo platform that they can further customize (or simply use -OOB). -- Provide the OpenTelemetry community with a living artifact that -demonstrates the features and capabilities of OTel APIs, SDKs, and tools. + OpenTelemetry instrumentation. +- Provide observability vendors with a single, well-supported, demo platform + that they can further customize (or simply use OOB). +- Provide the OpenTelemetry community with a living artifact that demonstrates + the features and capabilities of OTel APIs, SDKs, and tools. - Provide OpenTelemetry maintainers and WGs a platform to demonstrate new -features/concepts 'in the wild'. + features/concepts 'in the wild'. The following is a general description of the logical components of the demo application. ## Main Application -The bulk of the demo app is a self-contained -microservice-based application that does some useful 'real-world' work, such as -an eCommerce site. This application is composed of multiple services that -communicate with each other over gRPC and HTTP and runs on Kubernetes (or -Docker, locally). +The bulk of the demo app is a self-contained microservice-based application that +does some useful 'real-world' work, such as an eCommerce site. This application +is composed of multiple services that communicate with each other over gRPC and +HTTP and runs on Kubernetes (or Docker, locally). Each service shall be instrumented with OpenTelemetry for traces, metrics, and logs (as applicable/available). @@ -69,24 +67,24 @@ application written in Swift. ## Feature Flag Component -This component should consist of one (or more) services -that provides a simple feature flag configuration utility for the main -application. It is made up of a browser-based client/admin interface and a -backend service or services. The role of the client is to allow an operator to -visualize the available feature flags and toggle their state. The server should -provide a catalog of feature flags that main application services can register -with and interrogate for their current status and targeting rules. +This component should consist of one (or more) services that provides a simple +feature flag configuration utility for the main application. It is made up of a +browser-based client/admin interface and a backend service or services. The role +of the client is to allow an operator to visualize the available feature flags +and toggle their state. The server should provide a catalog of feature flags +that main application services can register with and interrogate for their +current status and targeting rules. The feature flag component should be implemented as an Erlang+Elixir/Phoenix service. The catalog of feature flags should be stored in a Database. ## Orchestration and Deployment -All services should run on Kubernetes. The -OpenTelemetry Collector should be deployed via the OpenTelemetry Operator, and -run in a sidecar + gateway mode. Telemetry from each pod should be routed from -agents to a gateway, and the gateway should export telemetry by default to an -open-source trace + metrics visualizer. +All services should run on Kubernetes. The OpenTelemetry Collector should be +deployed via the OpenTelemetry Operator, and run in a sidecar + gateway mode. +Telemetry from each pod should be routed from agents to a gateway, and the +gateway should export telemetry by default to an open-source trace + metrics +visualizer. For local/non-kubernetes deployment, the Collector should be deployed via compose file and monitor not only traces/metrics from applications, but also the diff --git a/content/en/docs/demo/requirements/system.md b/content/en/docs/demo/requirements/system.md index dc9d38183f5..c0347026361 100644 --- a/content/en/docs/demo/requirements/system.md +++ b/content/en/docs/demo/requirements/system.md @@ -9,5 +9,5 @@ following system requirements: 1. Your system must meet [Docker Desktop](https://docs.docker.com/desktop) system requirements or you should use your preferred Cloud Service. -2. The demo must be able to work on the following Operating Systems (OS): - Linux, macOS and Windows with documentation provided for each OS. +2. The demo must be able to work on the following Operating Systems (OS): Linux, + macOS and Windows with documentation provided for each OS. diff --git a/content/en/docs/demo/screenshots.md b/content/en/docs/demo/screenshots.md index 3ea41892639..e6f9362cdc2 100644 --- a/content/en/docs/demo/screenshots.md +++ b/content/en/docs/demo/screenshots.md @@ -6,34 +6,55 @@ aliases: [/docs/demo/demo_screenshots] ## Webstore -| Home Page | Checkout Screen | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| ![frontend-1](https://user-images.githubusercontent.com/15364991/194416314-d8210de5-814a-45b8-a47c-9d6bace51fa5.png) | ![frontend-2](https://user-images.githubusercontent.com/15364991/194416580-7f7ac8fe-85c0-462d-a896-6e0f6c95afac.png) | +| Home Page | Checkout Screen | +| --------------- | --------------- | +| ![frontend-1][] | ![frontend-2][] | ## Jaeger -| Jaeger UI | Trace View | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| ![jaeger-ui](https://user-images.githubusercontent.com/15364991/194417029-1e40f276-8785-47fb-b645-c90820c0ff52.png) | ![jaeger-trace-view](https://user-images.githubusercontent.com/15364991/194416769-188acc26-71c9-4611-8150-aa8639f11217.png) | +| Jaeger UI | Trace View | +| -------------- | ---------------------- | +| ![jaeger-ui][] | ![jaeger-trace-view][] | -| System Architecture| -| --- | -|![jaeger-system-architecture](https://user-images.githubusercontent.com/47896520/196496223-6d6ea729-5bea-4a8c-a2c6-cd51cce386ae.png)| +| System Architecture | +| ------------------------------- | +| ![jaeger-system-architecture][] | ## Prometheus -![prometheus](https://user-images.githubusercontent.com/47896520/196564627-ba9f5e91-a0fa-4bf0-beb1-f3a79ca309b5.png) +![prometheus][] ## Grafana -| Prometheus Data Source |Jaeger Data Source | -| --- | --- | -| ![grafana-prometheus](https://user-images.githubusercontent.com/47896520/196495466-86d3ce33-def4-4808-a6d9-3e32934bbf03.png) | ![gragana-jaeger](https://user-images.githubusercontent.com/47896520/196495509-c233d0d9-5e4c-4607-b609-dbf7869298d9.png) | +| Prometheus Data Source | Jaeger Data Source | +| ----------------------- | ------------------- | +| ![grafana-prometheus][] | ![gragana-jaeger][] | ## Feature Flag UI -![feature-flag-ui](https://user-images.githubusercontent.com/47896520/196496050-22fbbb56-9e62-46dd-a23c-c34c5566f7d2.png) +![feature-flag-ui][] ## Load Generator UI -![load-generator-ui](https://user-images.githubusercontent.com/47896520/196496589-bda802fc-aada-4e72-a184-93bb4711abca.png) +![load-generator-ui][] + +[feature-flag-ui]: + https://user-images.githubusercontent.com/47896520/196496050-22fbbb56-9e62-46dd-a23c-c34c5566f7d2.png +[frontend-1]: + https://user-images.githubusercontent.com/15364991/194416314-d8210de5-814a-45b8-a47c-9d6bace51fa5.png +[frontend-2]: + https://user-images.githubusercontent.com/15364991/194416580-7f7ac8fe-85c0-462d-a896-6e0f6c95afac.png +[grafana-prometheus]: + https://user-images.githubusercontent.com/47896520/196495466-86d3ce33-def4-4808-a6d9-3e32934bbf03.png +[gragana-jaeger]: + https://user-images.githubusercontent.com/47896520/196495509-c233d0d9-5e4c-4607-b609-dbf7869298d9.png +[jaeger-system-architecture]: + https://user-images.githubusercontent.com/47896520/196496223-6d6ea729-5bea-4a8c-a2c6-cd51cce386ae.png +[jaeger-trace-view]: + https://user-images.githubusercontent.com/15364991/194416769-188acc26-71c9-4611-8150-aa8639f11217.png +[jaeger-ui]: + https://user-images.githubusercontent.com/15364991/194417029-1e40f276-8785-47fb-b645-c90820c0ff52.png +[load-generator-ui]: + https://user-images.githubusercontent.com/47896520/196496589-bda802fc-aada-4e72-a184-93bb4711abca.png +[prometheus]: + https://user-images.githubusercontent.com/47896520/196564627-ba9f5e91-a0fa-4bf0-beb1-f3a79ca309b5.png diff --git a/content/en/docs/demo/services/accounting.md b/content/en/docs/demo/services/accounting.md index 2776b330c92..37dfad74337 100644 --- a/content/en/docs/demo/services/accounting.md +++ b/content/en/docs/demo/services/accounting.md @@ -4,8 +4,8 @@ linkTitle: Accounting aliases: [/docs/demo/services/accountingservice] --- -This service calculates the total amount of sold products. -This is only mocked and received orders are printed out. +This service calculates the total amount of sold products. This is only mocked +and received orders are printed out. [Accounting Service](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/accountingservice/) @@ -53,9 +53,8 @@ deferred function in main ### Adding Kafka ( Sarama ) auto-instrumentation This service will receive the processed results of the Checkout Service via a -Kafka topic. -To instrument the Kafka client the ConsumerHandler implemented by the developer -has to be wrapped. +Kafka topic. To instrument the Kafka client the ConsumerHandler implemented by +the developer has to be wrapped. ```go handler := groupHandler{} // implements sarama.ConsumerGroupHandler diff --git a/content/en/docs/demo/services/ad.md b/content/en/docs/demo/services/ad.md index b9ee4b64cf0..34074101244 100644 --- a/content/en/docs/demo/services/ad.md +++ b/content/en/docs/demo/services/ad.md @@ -4,8 +4,8 @@ linkTitle: Ad aliases: [/docs/demo/services/adservice] --- -This service determines appropriate ads to serve to users based on context -keys. The ads will be for products available in the store. +This service determines appropriate ads to serve to users based on context keys. +The ads will be for products available in the store. [Ad service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/adservice/) @@ -64,9 +64,8 @@ span status is set when an exception is caught. New spans can be created and started using `Tracer.spanBuilder("spanName").startSpan()`. Newly created spans should be set -into context using `Span.makeCurrent()`. The `getRandomAds` function will -create a new span, set it into context, perform an operation, and finally end -the span. +into context using `Span.makeCurrent()`. The `getRandomAds` function will create +a new span, set it into context, perform an operation, and finally end the span. ```java // create and start a new span manually @@ -92,9 +91,9 @@ the span. ### Initializing Metrics Similar to creating spans, the first step in creating metrics is initializing a -`Meter` instance, e.g. `GlobalOpenTelemetry.getMeter("adservice")`. From -there, use the various builder methods available on the `Meter` instance to -create the desired metric instrument, e.g.: +`Meter` instance, e.g. `GlobalOpenTelemetry.getMeter("adservice")`. From there, +use the various builder methods available on the `Meter` instance to create the +desired metric instrument, e.g.: ```java meter @@ -112,16 +111,16 @@ characters transformed to `_`. The following custom metrics are currently available: -* `app.ads.ad_requests`: A counter of ad requests with dimensions describing -whether the request was targeted with context keys or not, and whether the -response was targeted or random ads. +- `app.ads.ad_requests`: A counter of ad requests with dimensions describing + whether the request was targeted with context keys or not, and whether the + response was targeted or random ads. #### Auto-instrumented metrics The following auto-instrumented metrics are available for the application: -* [Runtime metrics for the JVM](/docs/reference/specification/metrics/semantic_conventions/runtime-environment-metrics/#jvm-metrics). -* [Latency metrics for RPCs](/docs/reference/specification/metrics/semantic_conventions/rpc-metrics/#rpc-server) +- [Runtime metrics for the JVM](/docs/reference/specification/metrics/semantic_conventions/runtime-environment-metrics/#jvm-metrics). +- [Latency metrics for RPCs](/docs/reference/specification/metrics/semantic_conventions/rpc-metrics/#rpc-server) ## Logs diff --git a/content/en/docs/demo/services/cart.md b/content/en/docs/demo/services/cart.md index 16c06f24975..3b87c064660 100644 --- a/content/en/docs/demo/services/cart.md +++ b/content/en/docs/demo/services/cart.md @@ -9,18 +9,17 @@ with a Redis caching service for fast access to shopping cart data. [Cart service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/cartservice/) -> **Note** -> OpenTelemetry for .NET uses the `System.Diagnostic` library as its API -> in lieu of the standard OpenTelemetry API. +> **Note** OpenTelemetry for .NET uses the `System.Diagnostic` library as its +> API in lieu of the standard OpenTelemetry API. ## Traces ### Initializing Tracing -OpenTelemetry is configured in the .NET DI container. The -`AddOpenTelemetry()` builder method is used to configure desired -instrumentation libraries, add exporters, and set other options. Configuration -of the exporter and resource attributes is performed through environment variables. +OpenTelemetry is configured in the .NET DI container. The `AddOpenTelemetry()` +builder method is used to configure desired instrumentation libraries, add +exporters, and set other options. Configuration of the exporter and resource +attributes is performed through environment variables. ```cs services.AddOpenTelemetry().WithTracing(builder => builder @@ -73,8 +72,8 @@ added. ### Initializing Metrics Similar to configuring OpenTelemetry Traces, the .NET DI container requires a -call to `AddOpenTelemetry()`. This builder configures desired -instrumentation libraries, exporters, etc. +call to `AddOpenTelemetry()`. This builder configures desired instrumentation +libraries, exporters, etc. ```cs services.AddOpenTelemetry().WithMetrics(builder => builder diff --git a/content/en/docs/demo/services/checkout.md b/content/en/docs/demo/services/checkout.md index b86aaf8ec6a..a232e79c550 100644 --- a/content/en/docs/demo/services/checkout.md +++ b/content/en/docs/demo/services/checkout.md @@ -75,8 +75,8 @@ func createClient(ctx context.Context, svcAddr string) (*grpc.ClientConn, error) ### Adding Kafka ( Sarama ) auto-instrumentation This service will write the processed results onto a Kafka topic which will then -be in turn be processed by other microservices. -To instrument the Kafka client the Producer has to be wrapped after it has been created. +be in turn be processed by other microservices. To instrument the Kafka client +the Producer has to be wrapped after it has been created. ```go saramaConfig := sarama.NewConfig() @@ -111,8 +111,8 @@ object. In the `PlaceOrder` function several attributes are added to the span. ### Add span events Adding span events is accomplished using `AddEvent` on the span object. In the -`PlaceOrder` function several span events are added. Some events have -additional attributes, others do not. +`PlaceOrder` function several span events are added. Some events have additional +attributes, others do not. Adding a span event without attributes: diff --git a/content/en/docs/demo/services/currency.md b/content/en/docs/demo/services/currency.md index 4e3a52c4955..100379ce3ee 100644 --- a/content/en/docs/demo/services/currency.md +++ b/content/en/docs/demo/services/currency.md @@ -13,8 +13,8 @@ currencies. ### Initializing Tracing -The OpenTelemetry SDK is initialized from `main` using the `initTracer` -function defined in `tacer_common.h` +The OpenTelemetry SDK is initialized from `main` using the `initTracer` function +defined in `tacer_common.h` ```cpp void initTracer() diff --git a/content/en/docs/demo/services/email.md b/content/en/docs/demo/services/email.md index 2f5b293f57e..bb138c1f53f 100644 --- a/content/en/docs/demo/services/email.md +++ b/content/en/docs/demo/services/email.md @@ -11,8 +11,8 @@ This service will send a confirmation email to the user when an order is placed. ## Initializing Tracing You will need to require the core OpenTelemetry SDK and exporter Ruby gems, as -well as any gem that will be needed for auto-instrumentation libraries -(ie: Sinatra) +well as any gem that will be needed for auto-instrumentation libraries (ie: +Sinatra) ```ruby require "opentelemetry/sdk" @@ -20,10 +20,10 @@ require "opentelemetry/exporter/otlp" require "opentelemetry/instrumentation/sinatra" ``` -The Ruby SDK uses OpenTelemetry standard environment variables to configure -OTLP export, resource attributes, and service name automatically. When -initializing the OpenTelemetry SDK, you will also specify which -auto-instrumentation libraries to leverage (ie: Sinatra) +The Ruby SDK uses OpenTelemetry standard environment variables to configure OTLP +export, resource attributes, and service name automatically. When initializing +the OpenTelemetry SDK, you will also specify which auto-instrumentation +libraries to leverage (ie: Sinatra) ```ruby OpenTelemetry::SDK.configure do |c| diff --git a/content/en/docs/demo/services/feature-flag.md b/content/en/docs/demo/services/feature-flag.md index 9a1e21ce9d0..33ec493a3d4 100644 --- a/content/en/docs/demo/services/feature-flag.md +++ b/content/en/docs/demo/services/feature-flag.md @@ -5,8 +5,8 @@ aliases: [/docs/demo/services/featureflagservice] --- This service is written in Erlang/Elixir and it is responsible for creating, -reading, updating and deleting feature flags in a PostgreSQL DB. -It is called by Product Catalog and Shipping services. +reading, updating and deleting feature flags in a PostgreSQL DB. It is called by +Product Catalog and Shipping services. [Feature Flag Service Source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/featureflagservice/) @@ -69,8 +69,8 @@ config :grpcbox, ### Add attributes to auto-instrumented spans -Adding attributes to a span is accomplished by using `?set_attribute` on the span -object. In the `get_flag` function two attributes are added to the span. +Adding attributes to a span is accomplished by using `?set_attribute` on the +span object. In the `get_flag` function two attributes are added to the span. ```elixir -include_lib("grpcbox/include/grpcbox.hrl"). diff --git a/content/en/docs/demo/services/fraud-detection.md b/content/en/docs/demo/services/fraud-detection.md index f647c9d9a89..690ccc27300 100644 --- a/content/en/docs/demo/services/fraud-detection.md +++ b/content/en/docs/demo/services/fraud-detection.md @@ -4,8 +4,8 @@ linkTitle: Fraud Detection aliases: [/docs/demo/services/frauddetectionservice] --- -This service analyses incoming orders and detects malicious customers. -This is only mocked and received orders are printed out. +This service analyses incoming orders and detects malicious customers. This is +only mocked and received orders are printed out. ## Auto-instrumentation diff --git a/content/en/docs/demo/services/frontend-proxy.md b/content/en/docs/demo/services/frontend-proxy.md index 85a7a60775c..a75d198c18d 100644 --- a/content/en/docs/demo/services/frontend-proxy.md +++ b/content/en/docs/demo/services/frontend-proxy.md @@ -4,16 +4,15 @@ linkTitle: Frontend Proxy aliases: [docs/demo/services/frontendproxy] --- -The frontend proxy is used as a reverse proxy for user-facing web -interfaces such as the frontend, Jaeger, Grafana, load generator, -and feature flag service. +The frontend proxy is used as a reverse proxy for user-facing web interfaces +such as the frontend, Jaeger, Grafana, load generator, and feature flag service. ## Enabling OpenTelemetry **NOTE: Only non-synthetic requests will trigger the envoy tracing.** -In order to enable Envoy to produce spans whenever receiving a request, -the following configuration is required: +In order to enable Envoy to produce spans whenever receiving a request, the +following configuration is required: ```yaml static_resources: @@ -26,14 +25,14 @@ static_resources: - filters: - name: envoy.filters.network.http_connection_manager typed_config: - "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager + '@type': type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: AUTO stat_prefix: ingress_http tracing: provider: name: envoy.tracers.opentelemetry typed_config: - "@type": type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig + '@type': type.googleapis.com/envoy.config.trace.v3.OpenTelemetryConfig grpc_service: envoy_grpc: cluster_name: opentelemetry_collector @@ -46,7 +45,7 @@ static_resources: lb_policy: ROUND_ROBIN typed_extension_protocol_options: envoy.extensions.upstreams.http.v3.HttpProtocolOptions: - "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions + '@type': type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions explicit_http_config: http2_protocol_options: {} load_assignment: @@ -60,5 +59,5 @@ static_resources: port_value: ${OTEL_COLLECTOR_PORT} ``` -Where `OTEL_COLLECTOR_HOST` and `OTEL_COLLECTOR_PORT` are passed via -environment variables. +Where `OTEL_COLLECTOR_HOST` and `OTEL_COLLECTOR_PORT` are passed via environment +variables. diff --git a/content/en/docs/demo/services/frontend.md b/content/en/docs/demo/services/frontend.md index 9bc7a7bcd5e..85359a97880 100644 --- a/content/en/docs/demo/services/frontend.md +++ b/content/en/docs/demo/services/frontend.md @@ -2,8 +2,8 @@ title: Frontend --- -The frontend is responsible to provide a UI for users, as well -as an API leveraged by the UI or other clients. The application is based on +The frontend is responsible to provide a UI for users, as well as an API +leveraged by the UI or other clients. The application is based on [Next.JS](https://nextjs.org/) to provide a React web-based UI and API routes. [Frontend source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/frontend/) @@ -14,24 +14,41 @@ It is recommended to use a Node required module when starting your NodeJS application to initialize the SDK and auto-instrumentation. When initializing the OpenTelemetry NodeJS SDK, you optionally specify which auto-instrumentation libraries to leverage, or make use of the `getNodeAutoInstrumentations()` -function which includes most popular frameworks. The `utils/telemetry/Instrumentation.js` -file contains all code required to initialize the SDK and auto-instrumentation -based on standard [OpenTelemetry environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md) +function which includes most popular frameworks. The +`utils/telemetry/Instrumentation.js` file contains all code required to +initialize the SDK and auto-instrumentation based on standard +[OpenTelemetry environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md) for OTLP export, resource attributes, and service name. ```javascript -const opentelemetry = require("@opentelemetry/sdk-node") -const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node") -const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc') -const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud') -const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws') -const { containerDetector } = require('@opentelemetry/resource-detector-container') -const { gcpDetector } = require('@opentelemetry/resource-detector-gcp') -const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources') +const opentelemetry = require('@opentelemetry/sdk-node'); +const { + getNodeAutoInstrumentations, +} = require('@opentelemetry/auto-instrumentations-node'); +const { + OTLPTraceExporter, +} = require('@opentelemetry/exporter-trace-otlp-grpc'); +const { + alibabaCloudEcsDetector, +} = require('@opentelemetry/resource-detector-alibaba-cloud'); +const { + awsEc2Detector, + awsEksDetector, +} = require('@opentelemetry/resource-detector-aws'); +const { + containerDetector, +} = require('@opentelemetry/resource-detector-container'); +const { gcpDetector } = require('@opentelemetry/resource-detector-gcp'); +const { + envDetector, + hostDetector, + osDetector, + processDetector, +} = require('@opentelemetry/resources'); const sdk = new opentelemetry.NodeSDK({ traceExporter: new OTLPTraceExporter(), - instrumentations: [ getNodeAutoInstrumentations() ], + instrumentations: [getNodeAutoInstrumentations()], resourceDetectors: [ containerDetector, envDetector, @@ -41,11 +58,11 @@ const sdk = new opentelemetry.NodeSDK({ alibabaCloudEcsDetector, awsEksDetector, awsEc2Detector, - gcpDetector - ] -}) + gcpDetector, + ], +}); -sdk.start() +sdk.start(); ``` Node required modules are loaded using the `--require` command line argument. @@ -65,48 +82,48 @@ the application using `npm start`. You can use the span object's `recordException` function to create a span event with the full stack trace of a handled error. When recording an exception also be sure to set the span's status accordingly. You can see this in the catch -block of the `NextApiHandler` function in the `utils/telemetry/InstrumentationMiddleware.ts` -file. +block of the `NextApiHandler` function in the +`utils/telemetry/InstrumentationMiddleware.ts` file. ```typescript - span.recordException(error as Exception); - span.setStatus({code: SpanStatusCode.ERROR}); +span.recordException(error as Exception); +span.setStatus({ code: SpanStatusCode.ERROR }); ``` ### Create new spans -New spans can be created and started using `Tracer.startSpan("spanName", options)`. -Several options can be used to specify how the span can be created. +New spans can be created and started using +`Tracer.startSpan("spanName", options)`. Several options can be used to specify +how the span can be created. - `root: true` will create a new trace, setting this span as the root. - `links` are used to specify links to other spans (even within another trace) -that should be referenced. + that should be referenced. - `attributes` are key/value pairs added to a span, typically used for -application context. + application context. ```typescript - span = tracer.startSpan(`HTTP ${method}`, { - root: true, - kind: SpanKind.SERVER, - links: [{context: syntheticSpan.spanContext()}], - attributes: { - "app.synthetic_request": true, - [SemanticAttributes.HTTP_TARGET]: target, - [SemanticAttributes.HTTP_STATUS_CODE]: response.statusCode, - [SemanticAttributes.HTTP_METHOD]: method, - [SemanticAttributes.HTTP_USER_AGENT]: headers['user-agent'] || '', - [SemanticAttributes.HTTP_URL]: `${headers.host}${url}`, - [SemanticAttributes.HTTP_FLAVOR]: httpVersion, - } - }); +span = tracer.startSpan(`HTTP ${method}`, { + root: true, + kind: SpanKind.SERVER, + links: [{ context: syntheticSpan.spanContext() }], + attributes: { + 'app.synthetic_request': true, + [SemanticAttributes.HTTP_TARGET]: target, + [SemanticAttributes.HTTP_STATUS_CODE]: response.statusCode, + [SemanticAttributes.HTTP_METHOD]: method, + [SemanticAttributes.HTTP_USER_AGENT]: headers['user-agent'] || '', + [SemanticAttributes.HTTP_URL]: `${headers.host}${url}`, + [SemanticAttributes.HTTP_FLAVOR]: httpVersion, + }, +}); ``` ## Browser Instrumentation The web-based UI that the frontend provides is also instrumented for web browsers. OpenTelemetry instrumentation is included as part of the Next.js App -component in `pages/_app.tsx`. Here instrumentation is imported and -initialized. +component in `pages/_app.tsx`. Here instrumentation is imported and initialized. ```typescript import FrontendTracer from '../utils/telemetry/FrontendTracer'; @@ -116,17 +133,21 @@ if (typeof window !== 'undefined') FrontendTracer(); The `utils/telemetry/FrontendTracer.ts` file contains code to intialize a TracerProvider, establish an OTLP export, register trace context propagators, -and register web specific auto-instrumentation libraries. Since the browser -will send data to an OpenTelemetry collector that will likely be on a separate +and register web specific auto-instrumentation libraries. Since the browser will +send data to an OpenTelemetry collector that will likely be on a separate domain, CORS headers are also setup accordingly. As part of the changes to carry over the `synthetic_request` attribute flag for the backend services, the `applyCustomAttributesOnSpan` configuration function -has been added to the `instrumentation-fetch` library custom span attributes logic -that way every browser-side span will include it. +has been added to the `instrumentation-fetch` library custom span attributes +logic that way every browser-side span will include it. ```typescript -import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core'; +import { + CompositePropagator, + W3CBaggagePropagator, + W3CTraceContextPropagator, +} from '@opentelemetry/core'; import { WebTracerProvider } from '@opentelemetry/sdk-trace-web'; import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'; import { registerInstrumentations } from '@opentelemetry/instrumentation'; @@ -140,7 +161,8 @@ const FrontendTracer = async () => { const provider = new WebTracerProvider({ resource: new Resource({ - [SemanticResourceAttributes.SERVICE_NAME]: process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME, + [SemanticResourceAttributes.SERVICE_NAME]: + process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME, }), }); @@ -151,7 +173,10 @@ const FrontendTracer = async () => { provider.register({ contextManager, propagator: new CompositePropagator({ - propagators: [new W3CBaggagePropagator(), new W3CTraceContextPropagator()], + propagators: [ + new W3CBaggagePropagator(), + new W3CTraceContextPropagator(), + ], }), }); @@ -163,7 +188,7 @@ const FrontendTracer = async () => { propagateTraceHeaderCorsUrls: /.*/, clearTimingResources: true, applyCustomAttributesOnSpan(span) { - span.setAttribute('app.synthetic_request', 'false'); + span.setAttribute('app.synthetic_request', 'false'); }, }, }), @@ -189,9 +214,8 @@ synthetic (from the load generator). Synthetic requests will force the creation of a new trace. The root span from the new trace will contain many of the same attributes as an HTTP request instrumented span. -To determine if a Baggage item is set, you can leverage the `propagation` API -to parse the Baggage header, and leverage the `baggage` API to get or -set entries. +To determine if a Baggage item is set, you can leverage the `propagation` API to +parse the Baggage header, and leverage the `baggage` API to get or set entries. ```typescript const baggage = propagation.getBaggage(context.active()); diff --git a/content/en/docs/demo/services/kafka.md b/content/en/docs/demo/services/kafka.md index 3baaaa95532..df842440bfd 100644 --- a/content/en/docs/demo/services/kafka.md +++ b/content/en/docs/demo/services/kafka.md @@ -2,8 +2,8 @@ title: Kafka --- -This is used as a message queue service to connect the checkout service with -the accounting and fraud detection services. +This is used as a message queue service to connect the checkout service with the +accounting and fraud detection services. [Kafka service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/kafka/) @@ -11,12 +11,13 @@ the accounting and fraud detection services. This service relies on the OpenTelemetry Java Agent and the built in [JMX Metric Insight Module](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/jmx-metrics/javaagent) -to capture [kafka broker metrics](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/javaagent/kafka-broker.md) +to capture +[kafka broker metrics](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/jmx-metrics/javaagent/kafka-broker.md) and send them off to the collector via OTLP. The agent is passed into the process using the `-javaagent` command line -argument. Command line arguments are added through the `KAFKA_OPTS` -in the `Dockerfile`. +argument. Command line arguments are added through the `KAFKA_OPTS` in the +`Dockerfile`. ```dockerfile ENV KAFKA_OPTS="-javaagent:/tmp/opentelemetry-javaagent.jar -Dotel.jmx.target.system=kafka-broker" diff --git a/content/en/docs/demo/services/load-generator.md b/content/en/docs/demo/services/load-generator.md index 2224808ffd8..1be10ab5e12 100644 --- a/content/en/docs/demo/services/load-generator.md +++ b/content/en/docs/demo/services/load-generator.md @@ -3,9 +3,9 @@ title: Load Generator aliases: [/docs/demo/services/loadgenerator] --- -The load generator is based on the Python load testing framework [Locust](https://locust.io). -By default it will simulate users requesting several different routes from the -frontend. +The load generator is based on the Python load testing framework +[Locust](https://locust.io). By default it will simulate users requesting +several different routes from the frontend. [Load generator source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/loadgenerator/) @@ -13,9 +13,10 @@ frontend. ### Initializing Tracing -Since this service is a [locustfile](https://docs.locust.io/en/stable/writing-a-locustfile.html), -the The OpenTelemetry SDK is initialized after the import statements. This code -will create a tracer provider, and establish a Span Processor to use. Export +Since this service is a +[locustfile](https://docs.locust.io/en/stable/writing-a-locustfile.html), the +The OpenTelemetry SDK is initialized after the import statements. This code will +create a tracer provider, and establish a Span Processor to use. Export endpoints, resource attributes, and service name are automatically set using [OpenTelemetry environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md). diff --git a/content/en/docs/demo/services/payment.md b/content/en/docs/demo/services/payment.md index 1a1c2238fd9..fc91f3bae4c 100644 --- a/content/en/docs/demo/services/payment.md +++ b/content/en/docs/demo/services/payment.md @@ -24,22 +24,40 @@ service name. It then `require`s your app at `./index.js` to start it up once the SDK is initialized. ```javascript -const opentelemetry = require("@opentelemetry/sdk-node") -const { getNodeAutoInstrumentations } = require("@opentelemetry/auto-instrumentations-node") -const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc') -const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc') -const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics') -const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud') -const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws') -const { containerDetector } = require('@opentelemetry/resource-detector-container') -const { gcpDetector } = require('@opentelemetry/resource-detector-gcp') -const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources') +const opentelemetry = require('@opentelemetry/sdk-node'); +const { + getNodeAutoInstrumentations, +} = require('@opentelemetry/auto-instrumentations-node'); +const { + OTLPTraceExporter, +} = require('@opentelemetry/exporter-trace-otlp-grpc'); +const { + OTLPMetricExporter, +} = require('@opentelemetry/exporter-metrics-otlp-grpc'); +const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics'); +const { + alibabaCloudEcsDetector, +} = require('@opentelemetry/resource-detector-alibaba-cloud'); +const { + awsEc2Detector, + awsEksDetector, +} = require('@opentelemetry/resource-detector-aws'); +const { + containerDetector, +} = require('@opentelemetry/resource-detector-container'); +const { gcpDetector } = require('@opentelemetry/resource-detector-gcp'); +const { + envDetector, + hostDetector, + osDetector, + processDetector, +} = require('@opentelemetry/resources'); const sdk = new opentelemetry.NodeSDK({ traceExporter: new OTLPTraceExporter(), - instrumentations: [ getNodeAutoInstrumentations() ], + instrumentations: [getNodeAutoInstrumentations()], metricReader: new PeriodicExportingMetricReader({ - exporter: new OTLPMetricExporter() + exporter: new OTLPMetricExporter(), }), resourceDetectors: [ containerDetector, @@ -50,15 +68,15 @@ const sdk = new opentelemetry.NodeSDK({ alibabaCloudEcsDetector, awsEksDetector, awsEc2Detector, - gcpDetector + gcpDetector, ], -}) +}); -sdk.start().then(() => require("./index")); +sdk.start().then(() => require('./index')); ``` -You can then use `opentelemetry.js` to start your app. -This can be done in the `ENTRYPOINT` command for the service's `Dockerfile`. +You can then use `opentelemetry.js` to start your app. This can be done in the +`ENTRYPOINT` command for the service's `Dockerfile`. ```dockerfile ENTRYPOINT [ "node", "./opentelemetry.js" ] @@ -72,17 +90,17 @@ Within the execution of auto-instrumented code you can get current span from context. ```javascript - const span = opentelemetry.trace.getActiveSpan(); +const span = opentelemetry.trace.getActiveSpan(); ``` Adding attributes to a span is accomplished using `setAttributes` on the span -object. In the `chargeServiceHandler` function an attributes is added to -the span as an anonymous object (map) for the attribute key/values pair. +object. In the `chargeServiceHandler` function an attributes is added to the +span as an anonymous object (map) for the attribute key/values pair. ```javascript - span.setAttributes({ - 'app.payment.amount': parseFloat(`${amount.units}.${amount.nanos}`) - }) +span.setAttributes({ + 'app.payment.amount': parseFloat(`${amount.units}.${amount.nanos}`), +}); ``` ### Span Exceptions and status @@ -93,8 +111,8 @@ be sure to set the span's status accordingly. You can see this in the `chargeServiceHandler` function ```javascript - span.recordException(err) - span.setStatus({ code: opentelemetry.SpanStatusCode.ERROR }) +span.recordException(err); +span.setStatus({ code: opentelemetry.SpanStatusCode.ERROR }); ``` ## Metrics @@ -109,11 +127,11 @@ instruments. const { metrics } = require('@opentelemetry/api-metrics'); const meter = metrics.getMeter('paymentservice'); -const transactionsCounter = meter.createCounter('app.payment.transactions') +const transactionsCounter = meter.createCounter('app.payment.transactions'); ``` -Meters and Instruments are supposed to stick around. This means you should -get a Meter or an Instrument once , and then re-use it as needed, if possible. +Meters and Instruments are supposed to stick around. This means you should get a +Meter or an Instrument once , and then re-use it as needed, if possible. ## Logs @@ -127,11 +145,15 @@ which is indicated with a span attribute. The `charge.js` file which does the actual payment processing, has logic to check the baggage. ```javascript - // check baggage for synthetic_request=true, and add charged attribute accordingly - const baggage = propagation.getBaggage(context.active()); - if (baggage && baggage.getEntry("synthetic_request") && baggage.getEntry("synthetic_request").value == "true") { - span.setAttribute('app.payment.charged', false); - } else { - span.setAttribute('app.payment.charged', true); - } +// check baggage for synthetic_request=true, and add charged attribute accordingly +const baggage = propagation.getBaggage(context.active()); +if ( + baggage && + baggage.getEntry('synthetic_request') && + baggage.getEntry('synthetic_request').value == 'true' +) { + span.setAttribute('app.payment.charged', false); +} else { + span.setAttribute('app.payment.charged', true); +} ``` diff --git a/content/en/docs/demo/services/product-catalog.md b/content/en/docs/demo/services/product-catalog.md index 4c8f7d38ce0..eed9559ca2e 100644 --- a/content/en/docs/demo/services/product-catalog.md +++ b/content/en/docs/demo/services/product-catalog.md @@ -83,8 +83,8 @@ context. ``` Adding attributes to a span is accomplished using `SetAttributes` on the span -object. In the `GetProduct` function an attribute for the product id is added -to the span. +object. In the `GetProduct` function an attribute for the product id is added to +the span. ```go span.SetAttributes( @@ -94,9 +94,9 @@ to the span. ### Setting span status -This service can catch and handle an error condition based on a feature flag. -In an error condition, the span status is set accordingly using `SetStatus` on -the span object. You can see this in the `GetProduct` function. +This service can catch and handle an error condition based on a feature flag. In +an error condition, the span status is set accordingly using `SetStatus` on the +span object. You can see this in the `GetProduct` function. ```go msg := fmt.Sprintf("Error: ProductCatalogService Fail Feature Flag Enabled") diff --git a/content/en/docs/demo/services/quote.md b/content/en/docs/demo/services/quote.md index 62c840b49bc..4fcf3f3289b 100644 --- a/content/en/docs/demo/services/quote.md +++ b/content/en/docs/demo/services/quote.md @@ -4,12 +4,12 @@ linkTitle: Quote aliases: [/docs/demo/services/quoteservice] --- -This service is responsible for calculating shipping costs, based on -the number of items to be shipped. The quote service is called from -Shipping Service via HTTP. +This service is responsible for calculating shipping costs, based on the number +of items to be shipped. The quote service is called from Shipping Service via +HTTP. -The Quote Service is implemented using the Slim framework and -php-di for managing the Dependency Injection. +The Quote Service is implemented using the Slim framework and php-di for +managing the Dependency Injection. The PHP instrumentation may vary when using a different framework. @@ -19,18 +19,19 @@ The PHP instrumentation may vary when using a different framework. ### Initializing Tracing -In this demo, the OpenTelemetry SDK has been automatically created as part -of SDK autoloading, which happens as part of composer autoloading. +In this demo, the OpenTelemetry SDK has been automatically created as part of +SDK autoloading, which happens as part of composer autoloading. -This is enabled by setting the environment variable `OTEL_PHP_AUTOLOAD_ENABLED=true`. +This is enabled by setting the environment variable +`OTEL_PHP_AUTOLOAD_ENABLED=true`. ```php require __DIR__ . '/../vendor/autoload.php'; ``` There are multiple ways to create or obtain a `Tracer`, in this example we -obtain one from the global tracer provider which was initialized above, as -part of SDK autoloading: +obtain one from the global tracer provider which was initialized above, as part +of SDK autoloading: ```php $tracer = Globals::tracerProvider()->getTracer('manual-instrumentation'); @@ -38,8 +39,8 @@ part of SDK autoloading: ### Manually creating spans -Creating a span manually can be done via a `Tracer`. The span will be default -be a child of the active span in the current execution context: +Creating a span manually can be done via a `Tracer`. The span will be default be +a child of the active span in the current execution context: ```php $span = Globals::tracerProvider() @@ -60,7 +61,8 @@ You can obtain the current span using `OpenTelemetry\API\Trace\Span`. ``` Adding attributes to a span is accomplished using `setAttribute` on the span -object. In the `calculateQuote` function 2 attributes are added to the `childSpan`. +object. In the `calculateQuote` function 2 attributes are added to the +`childSpan`. ```php $childSpan->setAttribute('app.quote.items.count', $numberOfItems); @@ -70,8 +72,8 @@ object. In the `calculateQuote` function 2 attributes are added to the `childSpa ### Add span events Adding span events is accomplished using `addEvent` on the span object. In the -`getquote` route span events are added. Some events have -additional attributes, others do not. +`getquote` route span events are added. Some events have additional attributes, +others do not. Adding a span event without attributes: diff --git a/content/en/docs/demo/services/recommendation.md b/content/en/docs/demo/services/recommendation.md index 3255095e2f5..f42b4fd84f2 100644 --- a/content/en/docs/demo/services/recommendation.md +++ b/content/en/docs/demo/services/recommendation.md @@ -11,9 +11,9 @@ based on existing product ids the user is browsing. ## Auto-instrumentation -This Python based service, makes use of the OpenTelemetry auto-instrumentor -for Python, accomplished by leveraging the `opentelemetry-instrument` Python -wrapper to run the scripts. This can be done in the `ENTRYPOINT` command for the +This Python based service, makes use of the OpenTelemetry auto-instrumentor for +Python, accomplished by leveraging the `opentelemetry-instrument` Python wrapper +to run the scripts. This can be done in the `ENTRYPOINT` command for the service's `Dockerfile`. ```dockerfile @@ -65,9 +65,9 @@ block ends execution. This is done in the `get_product_list` function. ### Initializing Metrics The OpenTelemetry SDK is initialized in the `__main__` code block. This code -will create a meter provider. Export -endpoints, resource attributes, and service name are automatically set by the -OpenTelemetry auto instrumentor based on environment variables. +will create a meter provider. Export endpoints, resource attributes, and service +name are automatically set by the OpenTelemetry auto instrumentor based on +environment variables. ```python meter = metrics.get_meter_provider().get_meter("recommendationservice") @@ -77,8 +77,8 @@ OpenTelemetry auto instrumentor based on environment variables. The following custom metrics are currently available: -* `app_recommendations_counter`: Cumulative count of # recommended - products per service call +- `app_recommendations_counter`: Cumulative count of # recommended products per + service call ### Auto-instrumented metrics @@ -86,9 +86,9 @@ The following metrics are available through auto-instrumentation, courtesy of the `opentelemetry-instrumentation-system-metrics`, which is installed as part of `opentelemetry-bootstrap` on building the recommendationservice Docker image: -* `runtime.cpython.cpu_time` -* `runtime.cpython.memory` -* `runtime.cpython.gc_count` +- `runtime.cpython.cpu_time` +- `runtime.cpython.memory` +- `runtime.cpython.gc_count` ## Logs diff --git a/content/en/docs/demo/services/shipping.md b/content/en/docs/demo/services/shipping.md index 1c0eb118064..8c4e72ae3ea 100644 --- a/content/en/docs/demo/services/shipping.md +++ b/content/en/docs/demo/services/shipping.md @@ -11,12 +11,12 @@ Shipping service is built primarily with Tonic, Reqwest, and OpenTelemetry Libraries/Components. Other sub-dependencies are included in `Cargo.toml`. Depending on your framework and runtime, you may consider consulting -[rust docs](/docs/instrumentation/rust/) to supplement. -You'll find examples of async and sync spans in quote requests and tracking ID's -respectively. +[rust docs](/docs/instrumentation/rust/) to supplement. You'll find examples of +async and sync spans in quote requests and tracking ID's respectively. The `build.rs` supports development outside docker, given a rust installation. -Otherwise, consider building with `docker compose` to edit / assess changes as needed. +Otherwise, consider building with `docker compose` to edit / assess changes as +needed. [Shipping service source](https://github.com/open-telemetry/opentelemetry-demo/blob/main/src/shippingservice/) @@ -55,18 +55,18 @@ fn init_tracer() -> Result { ``` Spans and other metrics are created in this example throughout `tokio` async -runtimes found within [`tonic` server -functions](https://github.com/hyperium/tonic/blob/master/examples/helloworld-tutorial.md#writing-our-server). -Be mindful of async runtime, [context -guards](https://docs.rs/opentelemetry/latest/opentelemetry/struct.ContextGuard.html), +runtimes found within +[`tonic` server functions](https://github.com/hyperium/tonic/blob/master/examples/helloworld-tutorial.md#writing-our-server). +Be mindful of async runtime, +[context guards](https://docs.rs/opentelemetry/latest/opentelemetry/struct.ContextGuard.html), and inability to move and clone `spans` when replicating from these samples. ### Adding gRPC instrumentation This service receives gRPC requests, which are instrumented in the middleware. -The root span is started and passed down as reference in the same thread -to another closure where we call `quoteservice`. +The root span is started and passed down as reference in the same thread to +another closure where we call `quoteservice`. ```rust let tracer = global::tracer("shippingservice"); @@ -102,20 +102,21 @@ to another closure where we call `quoteservice`. cx.span().set_attribute(semcov::trace::RPC_GRPC_STATUS_CODE.i64(RPC_GRPC_STATUS_CODE_OK)); ``` -Note that we create a context around the root span and send a clone to the -async function create_quote_from_count(). After create_quote_from_count() -completes, we can add additional attributes to the root span as appropriate. +Note that we create a context around the root span and send a clone to the async +function create_quote_from_count(). After create_quote_from_count() completes, +we can add additional attributes to the root span as appropriate. You may also notice the `attributes` set on the span in this example, and `events` propogated similarly. With any valid `span` pointer (attached to -context) the [OpenTelemetry API](https://docs.rs/opentelemetry/0.17.0/opentelemetry/trace/struct.SpanRef.html) +context) the +[OpenTelemetry API](https://docs.rs/opentelemetry/0.17.0/opentelemetry/trace/struct.SpanRef.html) will work. ### Adding HTTP instrumentation -A child *client* span is also produced for the outoing HTTP call to +A child _client_ span is also produced for the outoing HTTP call to `quoteservice` via the `reqwest` client. This span pairs up with the -corresponding `quoteservice` *server* span. The tracing instrumentation is +corresponding `quoteservice` _server_ span. The tracing instrumentation is implemented in the client middleware making use of the available `reqwest-middleware`, `reqwest-tracing` and `tracing-opentelementry` libraries: @@ -128,12 +129,12 @@ implemented in the client middleware making use of the available ### Add span attributes -Provided you are on the same thread, or in a context passed from a -span-owning thread, or a `ContextGuard` is in scope, you can get -an active span with `get_active_span`. You can find examples of all of these -in the demo, with context available in `shipping_service` for sync/async runtime. -You should consult `quote.rs` and/or the example above to see -context-passed-to-async runtime. +Provided you are on the same thread, or in a context passed from a span-owning +thread, or a `ContextGuard` is in scope, you can get an active span with +`get_active_span`. You can find examples of all of these in the demo, with +context available in `shipping_service` for sync/async runtime. You should +consult `quote.rs` and/or the example above to see context-passed-to-async +runtime. See below for a snippet from `shiporder` that holds context and a span in scope. This is appropriate in our case of a sync runtime. @@ -160,8 +161,9 @@ You must add attributes to a span in context with `set_attribute`, followed by a ### Add span events Adding span events is accomplished using `add_event` on the span object. Both -server routes, for `ShipOrderRequest` (sync) and `GetQuoteRequest` (async), -have events on spans. Attributes are not included here, but are [simple to include](https://docs.rs/opentelemetry/latest/opentelemetry/trace/trait.Span.html#method.add_event). +server routes, for `ShipOrderRequest` (sync) and `GetQuoteRequest` (async), have +events on spans. Attributes are not included here, but are +[simple to include](https://docs.rs/opentelemetry/latest/opentelemetry/trace/trait.Span.html#method.add_event). Adding a span event: diff --git a/content/en/docs/demo/tests.md b/content/en/docs/demo/tests.md index 61023832f1f..84d177748dc 100644 --- a/content/en/docs/demo/tests.md +++ b/content/en/docs/demo/tests.md @@ -2,10 +2,10 @@ title: Tests --- -Currently, the repository includes E2E tests for both the frontend and backend services. -For the Frontend we are using [Cypress](https://www.cypress.io/) execute the -different flows in the webstore. -While the backend services use [AVA](https://avajs.dev) as the main testing framework. +Currently, the repository includes E2E tests for both the frontend and backend +services. For the Frontend we are using [Cypress](https://www.cypress.io/) +execute the different flows in the webstore. While the backend services use +[AVA](https://avajs.dev) as the main testing framework. To run the test you can simply run `make run-tests` at the root directory.