Merge pull request #545 from logzio/app360docs

Updated App360 docs
logzio · Jun 13, 2024 · d3c7ebd · d3c7ebd
2 parents 0566a4d + 41c4fe6
commit d3c7ebd
Show file tree

Hide file tree

Showing 2 changed files with 296 additions and 866 deletions.
diff --git a/docs/shipping/App360/App360.md b/docs/shipping/App360/App360.md
@@ -0,0 +1,296 @@
+---
+id: Service-Performance-Monitoring-App360
+title: Service Performance Monitoring via App360
+overview: This integration allows you to configure App360 Service Performance Monitoring with OpenTelemetry collector and send spans and span metrics from your OpenTelemetry installation to Logz.io.
+product: ['tracing']
+os: ['windows', 'linux']
+filters: ['Other']
+logo: https://logzbucket.s3.eu-west-1.amazonaws.com/logz-docs/shipper-logos/span-metrics.png
+logs_dashboards: []
+logs_alerts: []
+logs2metrics: []
+metrics_dashboards: ['40ZpsSfzfGhbguMYoxwOqm', '5PFq9YHx2iQkwVMLCMOmjJ']
+metrics_alerts: []
+drop_filter: []
+---
+
+
+
+[App360](https://docs.logz.io/docs/user-guide/distributed-tracing/spm/) is a high-level monitoring dashboard within Logz.io that enables you to monitor your tracing services and operations. This integration allows you to configure Service Performance Monitoring with OpenTelemetry collector and send spans and App360 span metrics from your OpenTelemetry installation to Logz.io. 
+
+{@include: ../../_include/metric-shipping/custom-dashboard.html} Install the pre-built dashboard to enhance the observability of your metrics.
+
+
+<!-- logzio-inject:install:grafana:dashboards ids=["40ZpsSfzfGhbguMYoxwOqm, 5PFq9YHx2iQkwVMLCMOmjJ"] -->
+
+
+{@include: ../../_include/metric-shipping/generic-dashboard.html}
+
+
+
+## Architecture overview
+
+This integration is based on OpenTelemetry. It works as an add-on to existing OpenTelemetry installations. If you need to set up OpenTelemetry first, refer to our documentation on [OpenTelemetry](https://app.logz.io/#/dashboard/integrations/OpenTelemetry-data).
+
+The integration includes:
+
+* Configuring the OpenTelemetry collector to receive spans generated by your application instrumentation and send the spans and App360 span metrics to Logz.io
+
+On deployment, your OpenTelemetry instrumentation captures spans from your application and forwards them to the collector, which exports the spans and App360 span metrics data to your Logz.io account.
+
+:::note
+This integration uses OpenTelemetry Collector Contrib, not the OpenTelemetry Collector Core.
+:::
+
+
+
+
+## Set up your locally hosted OpenTelemetry installation to send spans and App360 span metrics to Logz.io
+
+**Before you begin, you'll need**:
+
+* An application instrumented with an OpenTelemetry instrumentation or any other supported instrumentations based on OpenTracing, Zipkin or Jaeger 
+* An active account with Logz.io
+* A Logz.io metrics account 
+
+
+### Configure OpenTelemetry collector
+
+#### Get the collector
+
+You can either download the OpenTelemetry collector to your local host or run the collector as a Docker container.
+
+##### Download locally
+
+Create a dedicated directory on the host of your application and download the [OpenTelemetry collector](https://github.com/open-telemetry/opentelemetry-collector/releases/tag/cmd%2Fbuilder%2Fv0.73.0) that is relevant to the operating system of your host.
+
+##### Run as a Docker container
+
+:::note
+If you are already running a Logz.io Docker image `logzio/otel-collector-traces`, the new image `logzio/otel-collector-spm` will replace it.
+:::
+
+In the same Docker network as your application:
+
+```shell
+docker pull otel/opentelemetry-collector-contrib:0.73.0
+```
+
+:::note
+This integration only works with a contrib image. 
+:::
+
+#### Create the config file
+
+After setting up the collector, create a configuration file `config.yaml` with the following parameters:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: "0.0.0.0:4317"
+      http:
+        endpoint: "0.0.0.0:4318"
+
+connectors:
+  spanmetrics:
+    aggregation_temporality: AGGREGATION_TEMPORALITY_CUMULATIVE
+    dimensions:
+    - name: rpc.grpc.status_code
+    - name: http.method
+    - name: http.status_code
+    - name: cloud.provider
+    - name: cloud.region
+    - name: db.system
+    - name: messaging.system
+    - default: DEV
+      name: env_id
+    dimensions_cache_size: 100000
+    histogram:
+      explicit:
+        buckets:
+        - 2ms
+        - 8ms
+        - 50ms
+        - 100ms
+        - 200ms
+        - 500ms
+        - 1s
+        - 5s
+        - 10s
+    metrics_expiration: 5m
+    resource_metrics_key_attributes:
+    - service.name
+    - telemetry.sdk.language
+    - telemetry.sdk.name
+
+exporters:
+  logzio/traces:
+    account_token: <<TRACING_SHIPPING_TOKEN>>
+    region: <<REGION_CODE>>
+  prometheusremotewrite/spm:
+    endpoint: https://<<LISTENER>>:8053
+    add_metric_suffixes: false
+    headers:
+      Authorization: Bearer <<SPM_SHIPPING_TOKEN>>
+
+processors:
+  batch:
+  tail_sampling:
+    policies:
+      [
+        {
+          name: policy-errors,
+          type: status_code,
+          status_code: {status_codes: [ERROR]}
+        },
+        {
+          name: policy-slow,
+          type: latency,
+          latency: {threshold_ms: 1000}
+        }, 
+        {
+          name: policy-random-ok,
+          type: probabilistic,
+          probabilistic: {sampling_percentage: 10}
+        }        
+      ]
+  metricstransform/metrics-rename:
+    transforms:
+      - include: ^duration.*$$
+        match_type: regexp
+        action: update
+        new_name: latency.
+      - include: calls
+        action: update
+        new_name: calls_total
+  metricstransform/labels-rename:
+    transforms:
+    - include: ^latency
+      action: update
+      match_type: regexp
+      operations:
+      - action: update_label
+        label: span.name
+        new_label: operation
+    - include: ^calls
+      action: update
+      match_type: regexp
+      operations:
+      - action: update_label
+        label: span.name
+        new_label: operation
+
+extensions:
+  pprof:
+    endpoint: :1777
+  zpages:
+    endpoint: :55679
+  health_check:
+
+service:
+  extensions: [health_check, pprof, zpages]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [tail_sampling, batch]
+      exporters: [logzio/traces, spanmetrics]
+    metrics/spanmetrics:
+      receivers: [spanmetrics]
+      processors: [metricstransform/metrics-rename, metricstransform/labels-rename]
+      exporters: [prometheusremotewrite/spm]      
+  telemetry:
+    logs:
+      level: "debug"
+```
+
+{@include: ../../_include/tracing-shipping/replace-tracing-token.html}
+
+{@include: ../../_include/tracing-shipping/replace-spm-token.html}
+  
+{@include: ../../_include/log-shipping/listener-var.html}
+
+{@include: ../../_include/tracing-shipping/tail-sampling.md}
+
+If you already have an OpenTelemetry installation, add to the configuration file of your existing OpenTelemetry collector the parameters described in the next steps.
+  
+
+
+
+### Start the collector
+
+#### Locally running collector
+
+Run the following command:
+
+```shell
+<path/to>/otelcontribcol_<VERSION-NAME> --config ./config.yaml
+```
+
+* Replace `<path/to>` with the path to the directory where you downloaded the collector.
+* Replace `<VERSION-NAME>` with the version name of the collector applicable to your system, e.g. `otelcontribcol_darwin_amd64`.
+
+
+
+#### Containerized collector
+
+Mount the `config.yaml` as volume to the `docker run` command and run it as follows.
+
+##### Linux
+
+```
+docker run  \
+--network host \
+-v <PATH-TO>/config.yaml:/etc/otelcol-contrib/config.yaml \
+otel/opentelemetry-collector-contrib:0.73.0
+
+```
+
+Replace `<PATH-TO>` to the path to the `config.yaml` file on your system.
+
+##### Windows
+
+```
+docker run  \
+-v <PATH-TO>/config.yaml:/etc/otelcol-contrib/config.yaml \
+-p 55678-55680:55678-55680 \
+-p 1777:1777 \
+-p 9411:9411 \
+-p 9943:9943 \
+-p 6831:6831 \
+-p 6832:6832 \
+-p 14250:14250 \
+-p 14268:14268 \
+-p 4317:4317 \
+-p 55681:55681 \
+otel/opentelemetry-collector-contrib:0.73.0
+```
+
+
+##### Optional parameters
+
+If required, you can add the following optional parameters as environment variables when running the container:
+
+| Parameter | Description | 
+|---|---|
+| LATENCY_HISTOGRAM_BUCKETS | Comma separated list of durations defining the latency histogram buckets. Default: `2ms`, `8ms`, `50ms`, `100ms`, `200ms`, `500ms`, `1s`, `5s`, `10s`   | 
+| SPAN_METRICS_DIMENSIONS | Each metric will have at least the following dimensions that are common across all spans: `Service name`, `Operation`, `Span kind`, `Status code`. The input is comma separated list of dimensions to add together with the default dimensions, for example: `region,http.url`. Each additional dimension is defined by a name from the span's collection of attributes or resource attributes. If the named attribute is missing in the span, this dimension will be omitted from the metric.   | 
+| SPAN_METRICS_DIMENSIONS_CACHE_SIZE | The maximum items number of `metric_key_to_dimensions_cache`. Default: `10000`. | 
+| AGGREGATION_TEMPORALITY | Defines the aggregation temporality of the generated metrics. One of either `cumulative` or `delta`. Default: `cumulative`. | 
+
+
+### Run the application
+
+{@include: ../../_include/tracing-shipping/collector-run-note.md}
+
+
+Run the application to generate traces.
+
+
+
+### Check Logz.io for your data
+
+Give your data some time to get from your system to ours, and then open [App360](https://app.logz.io/#/dashboard/spm/services/table?start=now-1h&end=now).
+
+