diff --git a/.spelling b/.spelling index 45ebd3136c..ca663aa799 100644 --- a/.spelling +++ b/.spelling @@ -684,6 +684,7 @@ NUL NULs Nurmamat O'Neal +oap OAuth OAuth2 oc @@ -1075,4 +1076,4 @@ Zipkin Ziyang Zolotusky ztunnel -ztunnels \ No newline at end of file +ztunnels diff --git a/content/en/docs/ops/integrations/skywalking/index.md b/content/en/docs/ops/integrations/skywalking/index.md new file mode 100644 index 0000000000..0f4ef5b184 --- /dev/null +++ b/content/en/docs/ops/integrations/skywalking/index.md @@ -0,0 +1,55 @@ +--- +title: Apache SkyWalking +description: How to integrate with Apache SkyWalking. +weight: 32 +keywords: [integration,skywalking,tracing] +owner: istio/wg-environments-maintainers +test: no +--- + +[Apache SkyWalking](http://skywalking.apache.org) is an application performance monitoring (APM) system, especially designed for +microservices, cloud native and container-based architectures. SkyWalking is a one-stop solution for observability that not only +provides distributed tracing ability like Jaeger and Zipkin, metrics ability like Prometheus and Grafana, logging ability like Kiali, +it also extends the observability to many other scenarios, such as associating the logs with traces, collecting system events and +associating the events with metrics, service performance profiling based on eBPF, etc. + +## Installation + +### Option 1: Quick start + +Istio provides a basic sample installation to quickly get SkyWalking up and running: + +{{< text bash >}} +$ kubectl apply -f @samples/addons/extras/skywalking.yaml@ +{{< /text >}} + +This will deploy SkyWalking into your cluster. This is intended for demonstration only, and is not tuned for performance or security. + +Istio proxies by default don't send traces to SkyWalking. You will also need to enable the SkyWalking tracing extension provider by adding +the following fields to your configuration: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + meshConfig: + extensionProviders: + - skywalking: + service: tracing.istio-system.svc.cluster.local + port: 11800 + name: skywalking + defaultProviders: + tracing: + - "skywalking" +{{< /text >}} + +### Option 2: Customizable install + +Consult the [SkyWalking documentation](http://skywalking.apache.org) to get started. No special changes are needed for SkyWalking to work with Istio. + +Once SkyWalking is installed, remember to modify the option `--set meshConfig.extensionProviders[0].skywalking.service` to point to the `skywalking-oap` deployment. +See [`ProxyConfig.Tracing`](/docs/reference/config/istio.mesh.v1alpha1/#Tracing) for advanced configuration such as TLS settings. + +## Usage + +For more information on using SkyWalking, please refer to the [SkyWalking task](/docs/tasks/observability/distributed-tracing/skywalking/). diff --git a/content/en/docs/tasks/observability/distributed-tracing/skywalking/index.md b/content/en/docs/tasks/observability/distributed-tracing/skywalking/index.md new file mode 100644 index 0000000000..53576b7014 --- /dev/null +++ b/content/en/docs/tasks/observability/distributed-tracing/skywalking/index.md @@ -0,0 +1,110 @@ +--- +title: Apache SkyWalking +description: Learn how to configure the proxies to send tracing requests to Apache SkyWalking. +weight: 10 +keywords: [telemetry,tracing,skywalking,span,port-forwarding] +owner: istio/wg-policies-and-telemetry-maintainers +test: yes +--- + +After completing this task, you will understand how to have your application participate in tracing with [Apache SkyWalking](https://skywalking.apache.org), +regardless of the language, framework, or platform you use to build it. + +This task uses the [Bookinfo](/docs/examples/bookinfo/) sample as the example application. + +To learn how Istio handles tracing, visit the [Distributed Tracing Overview](../overview/) section. + +## Configure tracing + +If you used an `IstioOperator` CR to install Istio, add the following field to your configuration: + +{{< text yaml >}} +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + meshConfig: + defaultProviders: + tracing: + - "skywalking" + enableTracing: true + extensionProviders: + - name: "skywalking" + skywalking: + service: tracing.istio-system.svc.cluster.local + port: 11800 +{{< /text >}} + +With this configuration, Istio is installed with a SkyWalking Agent as the default tracer. Trace data will be sent to a SkyWalking backend. + +In the default profile, the sampling rate is 1%. Increase it to 100% using the [Telemetry API](/docs/tasks/observability/telemetry/): + +{{< text bash >}} +$ kubectl apply -f - <}} + +## Deploy the SkyWalking Collector + +Follow the [SkyWalking installation](/docs/ops/integrations/skywalking/#installation) documentation to deploy SkyWalking into your cluster. + +## Deploy the Bookinfo Application + +Deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application. + +## Accessing the dashboard + +[Remotely Accessing Telemetry Addons](/docs/tasks/observability/gateways) details how to configure access to the Istio addons through a gateway. + +For testing (and temporary access), you may also use port-forwarding. Use the following, assuming you've deployed SkyWalking to the `istio-system` namespace: + +{{< text bash >}} +$ istioctl dashboard skywalking +{{< /text >}} + +## Generating traces using the Bookinfo sample + +1. When the Bookinfo application is up and running, access `http://$GATEWAY_URL/productpage` one or more times + to generate trace information. + + {{< boilerplate trace-generation >}} + +1. From the "General Service" panel, you can see the service list. + + {{< image link="./istio-service-list-skywalking.png" caption="Service List" >}} + +1. Select the `Trace` tab in the main content. You can see the trace list in the left sidebar and the trace details in the right panel: + + {{< image link="./istio-tracing-list-skywalking.png" caption="Trace View" >}} + +1. The trace is comprised of a set of spans, + where each span corresponds to a Bookinfo service, invoked during the execution of a `/productpage` request, or + internal Istio component, for example: `istio-ingressgateway`. + +## Explore SkyWalking's official demo application + +In this tutorial, we use the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application, in this sample application +there is no SkyWalking agent installed to the services, all the traces are generated by the sidecar proxies. + +If you want to explore more about [SkyWalking's language agents](https://skywalking.apache.org/docs/#Agent), the SkyWalking team also provides +[a demo application](http://github.com/apache/skywalking-showcase) that is integrated with the language agents and you can have more detailed traces as well as other language agent specific +features such as profiling. + +## Cleanup + +1. Remove any `istioctl` processes that may still be running using control-C or: + + {{< text bash >}} + $ killall istioctl + {{< /text >}} + +1. If you are not planning to explore any follow-on tasks, refer to the + [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions + to shutdown the application. diff --git a/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-service-list-skywalking.png b/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-service-list-skywalking.png new file mode 100644 index 0000000000..f892194ed6 Binary files /dev/null and b/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-service-list-skywalking.png differ diff --git a/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-tracing-list-skywalking.png b/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-tracing-list-skywalking.png new file mode 100644 index 0000000000..6bae9b4b8c Binary files /dev/null and b/content/en/docs/tasks/observability/distributed-tracing/skywalking/istio-tracing-list-skywalking.png differ diff --git a/content/en/docs/tasks/observability/distributed-tracing/skywalking/snips.sh b/content/en/docs/tasks/observability/distributed-tracing/skywalking/snips.sh new file mode 100644 index 0000000000..e99492b3b0 --- /dev/null +++ b/content/en/docs/tasks/observability/distributed-tracing/skywalking/snips.sh @@ -0,0 +1,59 @@ +#!/bin/bash +# shellcheck disable=SC2034,SC2153,SC2155,SC2164 + +# Copyright Istio Authors. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +#################################################################################################### +# WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL MARKDOWN FILE: +# docs/tasks/observability/distributed-tracing/skywalking/index.md +#################################################################################################### +source "content/en/boilerplates/snips/trace-generation.sh" + +! read -r -d '' snip_configure_tracing_1 <<\ENDSNIP +apiVersion: install.istio.io/v1alpha1 +kind: IstioOperator +spec: + meshConfig: + defaultProviders: + tracing: + - "skywalking" + enableTracing: true + extensionProviders: + - name: "skywalking" + skywalking: + service: tracing.istio-system.svc.cluster.local + port: 11800 +ENDSNIP + +snip_configure_tracing_2() { +kubectl apply -f - <