Add Sumo examples (#681)

examples/README.md

@@ -0,0 +1,45 @@
+# Examples
+## Kubernetes configuration
+
+### Helm chart values template
+[kubernetes/custom-values.yaml](./kubernetes/custom-values.yaml) contains 
+an example template for Sumologic Kubernetes Collection Helm chart, which
+installs OpenTelemetry Collector in Agent and Gateway configuration, as described
+in the [documentation](https://help.sumologic.com/Traces/Getting_Started_with_Transaction_Tracing/Set_up_traces_collection_for_Kubernetes_environments).
+
+After filling the template values, you can install it following
+[Sumologic Kubernetes Collection installation instructions](https://github.com/SumoLogic/sumologic-kubernetes-collection/blob/release-v2.0/deploy/docs/Installation_with_Helm.md)
+For example, by running following commands:
+```shell
+helm repo add sumologic https://sumologic.github.io/sumologic-kubernetes-collection
+kubectl create namespace sumologic
+helm upgrade --install my-release -n sumologic sumologic/sumologic -f custom-values.yaml 
+```
+
+### Helm chart values template with cascading filter enabled
+
+Additionally, [kubernetes/custom-values-cascading-filter.yaml](./kubernetes/custom-values-cascading-filter.yaml) 
+includes an alternative example template that enables cascading filter,
+as described in [trace filtering documentation](https://help.sumologic.com/Traces/Getting_Started_with_Transaction_Tracing/What_if_I_don't_want_to_send_all_the_tracing_data_to_Sumo_Logic%3F).
+Note that cascading filter is currently supported only for single-instance
+OpenTelemetry Collector deployments.
+
+## Non-kubernetes configuration
+
+### Agent configuration (should be run on each host/node)
+[non-kubernetes/agent-configuration-template.yaml](non-kubernetes/agent-configuration-template.yaml) contains
+an OpenTelemetry Collector YAML file which includes configuration
+for OpenTelemetry Collector running in Agent mode. It should be 
+deployed on each host/node within the system.
+
+### Gateway configuration (should be run per each cluster/data-center/etc.)
+[non-kubernetes/gateway-configuration-template.yaml](non-kubernetes/gateway-configuration-template.yaml) contains
+an OpenTelemetry Collector YAML file which includes configuration
+for OpenTelemetry Collector running in Gateway mode. 
+
+Additionally, for [non-kubernetes/gateway-configuration-template-with-cascading-filter.yaml](non-kubernetes/gateway-configuration-template-with-cascading-filter.yaml)
+the configuration also includes cascading filter config,
+which is described in more detail in [trace filtering documentation](https://help.sumologic.com/Traces/Getting_Started_with_Transaction_Tracing/What_if_I_don't_want_to_send_all_the_tracing_data_to_Sumo_Logic%3F).
+
+Please refer to [relevant documentation](https://help.sumologic.com/Traces/Getting_Started_with_Transaction_Tracing/Set_up_traces_collection_for_other_environments)
+for more details.

examples/kubernetes/custom-values-cascading-filter.yaml

@@ -0,0 +1,73 @@
+sumologic:
+  accessId: <ENTER_YOUR_SUMOLOGIC_ACCESS_ID>
+  accessKey: <ENTER_YOUR_SUMOLOGIC_ACCESS_KEY>
+  clusterName: <ENTER_YOUR_CLUSTER_NAME>
+  traces:
+    enabled: true
+## Following enables OpenTelemetry Agent which runs on each node as a DaemonSet
+otelagent:
+  enabled:
+    true
+## Following configures OpenTelemetry Collector (gateway)
+## Note that if cascading_filter is used, deployment must include only a single instance
+otelcol:
+  metrics:
+    ## This enables exposing OpenTelemetry Collector metrics. Note that they will consume your DPM
+    ## hence by default they are disabled
+    enabled:
+      true
+  config:
+    processors:
+      ## Following enables a smart cascading filtering rules with preset limits.
+      cascading_filter:
+        ## (default = 30s): Wait time since the first span of a trace before making
+        ## a filtering decision
+        decision_wait: 30s
+        ## (default = 50000): Number of traces kept in memory
+        num_traces: 50000
+        ## (default = 0): Expected number of new traces (helps in allocating data structures)
+        expected_new_traces_per_sec: 100
+        ## (default = 0): defines maximum number of spans per second
+        spans_per_second: 1600
+        ## (default = 0.2): Ratio of spans that are always probabilistically filtered
+        ## (hence might be used for metrics calculation).
+        probabilistic_filtering_ratio: 0.2
+        ## (no default): Policies used to make a sampling decision
+        policies:
+          - name: sampling-priority,
+            ## string_attribute: allows to specify conditions that need to be met
+            string_attribute: {
+              key: sampling.priority, values: [ "1" ]
+            },
+            ## Spans_per_second: max number of emitted spans per second by this policy.
+            spans_per_second: 500
+          - name: everything-else
+            ## This selects all traces, up the to the global limit
+            spans_per_second: -1
+          ## Following are some examples of other rules that could be used
+          # - name: extended-duration
+          #  ## Spans_per_second: max number of emitted spans per second by this policy.
+          #  spans_per_second: 500
+          #   properties:
+          #     ## Selects the span if the duration is greater or equal the given
+          #     ## value (use s or ms as the suffix to indicate unit).
+          #     min_duration: 5s
+          # - name: "status_code_condition",
+          #   ## Spans_per_second: max number of emitted spans per second by this policy.
+          #   spans_per_second: 500,
+          #   ## numeric_attribute: provides a list of conditions that need to be met
+          #   numeric_attribute: {
+          #     key: "http.status_code", min_value: 400, max_value: 999
+          #   }
+          # - name: everything-that-is-not-healthcheck
+          #   ## This selects all traces where there is NO span starting with `health` operation name
+          #   ## If employed, "everything-else" rule must be replaced with it
+          #   properties:
+          #     name_pattern: "^(healthcheck|otherhealthcheck).*"
+          #   invert_match: true
+          #   spans_per_second: -1
+    service:
+      pipelines:
+        traces:
+          ## This is required to enable cascading_filter
+          processors: [memory_limiter, k8s_tagger, source, resource, cascading_filter, batch]

examples/kubernetes/custom-values.yaml

@@ -0,0 +1,16 @@
+sumologic:
+  accessId: <ENTER_YOUR_SUMOLOGIC_ACCESS_ID>
+  accessKey: <ENTER_YOUR_SUMOLOGIC_ACCESS_KEY>
+  clusterName: <ENTER_YOUR_CLUSTER_NAME>
+  traces:
+    enabled: true
+otelcol:
+  ## This enables exposing OpenTelemetry Collector metrics. Note that they will consume your DPM
+  ## hence by default they are disabled
+  metrics:
+    enabled:
+      true
+## Following enables OpenTelemetry Agent which runs on each node as a DaemonSet
+otelagent:
+  enabled:
+    true

examples/non-kubernetes/agent-configuration-template.yaml

@@ -0,0 +1,70 @@
+receivers:
+  jaeger:
+    protocols:
+      thrift_compact:
+        endpoint: "0.0.0.0:6831"
+      thrift_binary:
+        endpoint: "0.0.0.0:6832"
+      grpc:
+        endpoint: "0.0.0.0:14250"
+      thrift_http:
+        endpoint: "0.0.0.0:14268"
+  opencensus:
+    endpoint: "0.0.0.0:55678"
+  otlp:
+    protocols:
+      grpc:
+        endpoint: "0.0.0.0:4317"
+      http:
+        endpoint: "0.0.0.0:55681"
+  zipkin:
+    endpoint: "0.0.0.0:9411"
+processors:
+  ## The memory_limiter processor is used to prevent out of memory situations on the collector.
+  memory_limiter:
+    ## check_interval is the time between measurements of memory usage for the
+    ## purposes of avoiding going over the limits. Defaults to zero, so no
+    ## checks will be performed. Values below 1 second are not recommended since
+    ## it can result in unnecessary CPU consumption.
+    check_interval: 5s
+
+    ## Maximum amount of memory, in MiB, targeted to be allocated by the process heap.
+    ## Note that typically the total memory usage of process will be about 50MiB higher
+    ## than this value.
+    limit_mib: 500
+
+  ## Please enable/disable accordingly if on AWS, GCE, ECS, elastic_beanstalk or neither
+  resourcedetection:
+    detectors: [ ec2, gce, ecs, elastic_beanstalk ]
+    timeout: 5s
+    override: false
+
+  ## The batch processor accepts spans and places them into batches grouped by node and resource
+  batch:
+    ## Number of spans after which a batch will be sent regardless of time
+    send_batch_size: 256
+    ## Never more than this many spans are being sent in a batch
+    send_batch_max_size: 512
+    ## Time duration after which a batch will be sent regardless of size
+    timeout: 5s
+
+extensions:
+  health_check: {}
+exporters:
+  otlp:
+    ## Please enter OpenTelemetry Collector Gateway address here
+    endpoint: HOSTNAME
+    insecure: true
+  ## Following generates verbose logs with span content, useful to verify what
+  ## metadata is being tagged. To enable, uncomment and add "logging" to exporters below.
+  ## There are two levels that could be used: `debug` and `info` with the former
+  ## being much more verbose and including (sampled) spans content
+  # logging:
+  #   loglevel: debug
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [jaeger, opencensus, otlp, zipkin]
+      processors: [memory_limiter, resourcedetection, batch]
+      exporters: [otlp]

examples/non-kubernetes/gateway-configuration-template-with-cascading-filter.yaml

@@ -0,0 +1,104 @@
+receivers:
+  jaeger:
+    protocols:
+      thrift_compact:
+        endpoint: "0.0.0.0:6831"
+      thrift_binary:
+        endpoint: "0.0.0.0:6832"
+      grpc:
+        endpoint: "0.0.0.0:14250"
+      thrift_http:
+        endpoint: "0.0.0.0:14268"
+  opencensus:
+    endpoint: "0.0.0.0:55678"
+  otlp:
+    protocols:
+      grpc:
+        endpoint: "0.0.0.0:4317"
+      http:
+        endpoint: "0.0.0.0:55681"
+  zipkin:
+    endpoint: "0.0.0.0:9411"
+processors:
+  ## The memory_limiter processor is used to prevent out of memory situations on the collector.
+  memory_limiter:
+    ## check_interval is the time between measurements of memory usage for the
+    ## purposes of avoiding going over the limits. Defaults to zero, so no
+    ## checks will be performed. Values below 1 second are not recommended since
+    ## it can result in unnecessary CPU consumption.
+    check_interval: 5s
+
+    ## Maximum amount of memory, in MiB, targeted to be allocated by the process heap.
+    ## Note that typically the total memory usage of process will be about 50MiB higher
+    ## than this value.
+    limit_mib: 1900
+
+  ## Smart cascading filtering rules with preset limits.
+  cascading_filter:
+    ## (default = 30s): Wait time since the first span of a trace arrived before making
+    ## a filtering decision
+    decision_wait: 30s
+    ## (default = 50000): Maximum number of traces kept in memory
+    num_traces: 100000
+    ## (default = 0): Expected number of new traces (helps in allocating data structures)
+    expected_new_traces_per_sec: 1000
+    ## (default = 0): defines the global limit of maximum number of spans per second
+    ## that are going to be emitted
+    spans_per_second: 1660
+    ## (default = 0.2): Ratio of spans that are always probabilistically filtered
+    ## (hence might be used for metrics calculation).
+    probabilistic_filtering_ratio: 0.2
+    ## (no default): Policies used to make a sampling decision
+    policies:
+      - name: sampling-priority,
+        ## string_attribute: allows to specify conditions that need to be met
+        string_attribute: {
+          key: sampling.priority, values: [ "1" ]
+        },
+        ## Spans_per_second: max number of emitted spans per second by this policy.
+        spans_per_second: 500
+      - name: extended-duration
+        ## Spans_per_second: max number of emitted spans per second by this policy.
+        spans_per_second: 500
+        properties:
+          ## Selects the span if the duration is greater or equal the given
+          ## value (use s or ms as the suffix to indicate unit).
+          min_duration: 5s
+      - name: "status_code_condition",
+        ## Spans_per_second: max number of emitted spans per second by this policy.
+        spans_per_second: 500,
+        ## numeric_attribute: provides a list of conditions that need to be met
+        numeric_attribute: {
+          key: "http.status_code", min_value: 400, max_value: 999
+        }
+      - name: everything-else
+        ## This selects all traces, up the to the global limit
+        spans_per_second: -1
+
+  ## The batch processor accepts spans and places them into batches grouped by node and resource
+  batch:
+    ## Number of spans after which a batch will be sent regardless of time
+    send_batch_size: 256
+    ## Never more than this many spans are being sent in a batch
+    send_batch_max_size: 512
+    ## Time duration after which a batch will be sent regardless of size
+    timeout: 5s
+
+extensions:
+  health_check: {}
+exporters:
+  zipkin:
+    endpoint: ENDPOINT_URL
+  ## Following generates verbose logs with span content, useful to verify what
+  ## metadata is being tagged. To enable, uncomment and add "logging" to exporters below.
+  ## There are two levels that could be used: `debug` and `info` with the former
+  ## being much more verbose and including (sampled) spans content
+  # logging:
+  #   loglevel: debug
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [jaeger, opencensus, otlp, zipkin]
+      processors: [memory_limiter, cascading_filter, batch]
+      exporters: [zipkin]

examples/non-kubernetes/gateway-configuration-template.yaml

@@ -0,0 +1,62 @@
+receivers:
+  jaeger:
+    protocols:
+      thrift_compact:
+        endpoint: "0.0.0.0:6831"
+      thrift_binary:
+        endpoint: "0.0.0.0:6832"
+      grpc:
+        endpoint: "0.0.0.0:14250"
+      thrift_http:
+        endpoint: "0.0.0.0:14268"
+  opencensus:
+    endpoint: "0.0.0.0:55678"
+  otlp:
+    protocols:
+      grpc:
+        endpoint: "0.0.0.0:4317"
+      http:
+        endpoint: "0.0.0.0:55681"
+  zipkin:
+    endpoint: "0.0.0.0:9411"
+processors:
+  ## The memory_limiter processor is used to prevent out of memory situations on the collector.
+  memory_limiter:
+    ## check_interval is the time between measurements of memory usage for the
+    ## purposes of avoiding going over the limits. Defaults to zero, so no
+    ## checks will be performed. Values below 1 second are not recommended since
+    ## it can result in unnecessary CPU consumption.
+    check_interval: 5s
+
+    ## Maximum amount of memory, in MiB, targeted to be allocated by the process heap.
+    ## Note that typically the total memory usage of process will be about 50MiB higher
+    ## than this value.
+    limit_mib: 1900
+
+  ## The batch processor accepts spans and places them into batches grouped by node and resource
+  batch:
+    ## Number of spans after which a batch will be sent regardless of time
+    send_batch_size: 256
+    ## Never more than this many spans are being sent in a batch
+    send_batch_max_size: 512
+    ## Time duration after which a batch will be sent regardless of size
+    timeout: 5s
+
+extensions:
+  health_check: {}
+exporters:
+  zipkin:
+    endpoint: ENDPOINT_URL
+  ## Following generates verbose logs with span content, useful to verify what
+  ## metadata is being tagged. To enable, uncomment and add "logging" to exporters below.
+  ## There are two levels that could be used: `debug` and `info` with the former
+  ## being much more verbose and including (sampled) spans content
+  # logging:
+  #   loglevel: debug
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [jaeger, opencensus, otlp, zipkin]
+      processors: [memory_limiter, batch]
+      exporters: [zipkin]