LightStep Documentation

Welcome to the LightStep developer hub. You'll find comprehensive guides and documentation to help you start working with LightStep as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Instrument with Istio as Your Service Mesh

LightStep works with many service meshes, and LightStep + Istio is an easy way to get quick visibility into service performance and availability from the perspective of the service mesh.

Istio Proxy, based on Envoy, uses OpenTracing (OT) to start new traces and join existing traces, based on HTTP request headers. After configuring Istio, it sends all span data it generates to Satellites. You start seeing traces and spans in LightStep immediately - no additional code-level instrumentation is needed. By default, all HTTP requests are captured (to see end-to-end traces, your code needs to forward OT headers even if it does not join the traces).

Wondering about tracers with Istio?

If you only want to collect tracing spans directly from Istio (and not add specific instrumentation directly to your code), then you don't need to configure any tracers, as long as your services forward the HTTP headers generated by traces.

These steps use the Google Cloud Platform with the Google Cloud Shell, Kubernetes, and Helm. You'll learn how to install Istio and configure it to work with LightStep in that environment.

After that, you can install Istio's Bookinfo sample application and see example spans immediately in LightStep.


You'll need the following to configure Istio:

LightStep Public and Developer Satellites
  • Copy and download the cacert.pem file at the end of this topic to a local directory.
  • Satellite pool address in the format <host>:<port>.
On-Premise Satellites
  • Satellite pool address in the format <host>:<port>.
    You find this in your configuration file.
  • Confirm that you configured your Satellites to use TLS certs and that they expose a secure gRPC port.

Download and Install Istio

These steps use Google Cloud, Cloud Shell, and the Kubernetes API.

  1. Create environment variables for the following:
    • Cluster name: The name for the Kubernetes cluster in which you will deploy your Istio-enabled application. You can use any unique name.
    • Project name: The Project_ID for your Google Cloud project where you are installing your Istio-enabled application.
    • Google Cloud Compute Engine zone: The zone where this instance will be hosted. You can choose any supported zone.
    • LightStep project's access token: You can find this here.
    • Istio version: The version of Istio to install.
export CLUSTER_NAME=my-cluster
export PROJECT_NAME=my-project
export ZONE=us-central1-a
export ISTIO_VERSION=1.1.5
  1. Download Istio from Github.
  1. Untar the archive and go to the install directory.
tar zxvf istio-$ISTIO_VERSION-osx.tar.gz

  1. Install Helm following the instructions here. Helm templates provide easy customization of Istio's configuration.

  2. Create a Kubernetes cluster of three nodes using the variables set in Step 1.

gcloud container clusters create $CLUSTER_NAME --cluster-version latest --machine-type n1-standard-2 --num-nodes 3 --preemptible --zone $ZONE --project $PROJECT_NAME
  1. Update the local kubectl credentials for the cluster.
gcloud container clusters get-credentials $CLUSTER_NAME --zone $ZONE --project $PROJECT_NAME
  1. Grant cluster-admin role to the current user.
kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud config get-value core/account)
  1. Create a namespace for Istio.
kubectl create namespace istio-system

Configure Istio

  1. Install the chart that initializes Istio.
helm template install/kubernetes/helm/istio-init --name istio-init --namespace istio-system | kubectl apply -f -
  1. Verify that Istio CRDs were committed to the Kubernetes api-server.
kubectl get crds | grep '\|' | wc -l
  1. Set configuration parameters in the helm template and apply to Istio.
    For public or developer Satellites, use for the value of global.tracer.lightstep.address.
    For on-premise Satellites, use the address from your configuration file.
helm template --set pilot.traceSampling=100 --set global.proxy.tracer="lightstep" --set global.tracer.lightstep.address="" --set global.tracer.lightstep.accessToken=$ACCESS_TOKEN --set --set global.tracer.lightstep.cacertPath="/etc/lightstep/cacert.pem" install/kubernetes/helm/istio --name istio --namespace istio-system > $HOME/istio.yaml

kubectl apply -f ~/istio.yaml
  1. Public Satellites and Developer Satellite users only: Add the CA cert used for signing the satellite's identity as a secret. This is the cacert file you downloaded in the Prerequisites.
kubectl create secret generic lightstep.cacert --from-file=cacert.pem

Istio is now configured to work with LightStep!

To see example traces, follow the next section to install Istio's Bookfinder sample app.

Install the Bookfinder App and Send Traces

Istio's Bookfinder app uses four microservices to display information about a book.

  1. Enable sidecar injection in the default namespace.
kubectl label namespace default istio-injection=enabled
  1. Deploy the application to Kubernetes.
kubectl apply -f samples/bookinfo/platform/kube/bookinfo.yaml
  1. Create the ingress gateway for the application.
kubectl apply -f samples/bookinfo/networking/bookinfo-gateway.yaml
  1. Set the INGRESS_HOST and INGRESS_PORT variables for accessing the gateway.
export INGRESS_HOST=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
export INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?("http2")].port}')
export SECURE_INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?("https")].port}')
  1. Set the GATEWAY_URL.
  1. Open the app. You can find the URL of the Bookfinder app using the sensible-browser command.
    The Bookfinder app opens in your browser.
  1. Click the browser's refresh button a few times to create some spans.

You now have sent data to LightStep created by the refresh requests (or anything else you've clicked in the browser).

View Traces in LightStep

Now that you have some trace data created, go into LightStep to see it!

No trace data?

If you open LightStep and don't see any data, it's likely because too much time has gone by since you last refreshed the browser (causing a request). Refresh the Bookfinder window a few times and then go back into LightStep.

  1. Open LightStep. You'll see the three services from the Bookfinder app listed on the Services page.
  1. Click the Explorer tab to view the generated latency histogram.

You can see all the requests broken down by service and operation.

  1. Click on the first row in the table of example traces below the latency histogram to see span details corresponding to that operation. Each span corresponds to a Bookinfo service invoked during the execution of a /productpage request.

    Each RPC request results in two spans - one for the client and one for the server. For example, the call from productpage to reviews starts with the reviews.default.svc.cluster.local:9080/* operation and the productpage.default: proxy client service. This service represents the client-side span of the call. It took 21.7 ms.

    The second span for the reviews.default.svc.cluster.local:9080/* operation and reviews.default: proxy server service is a child of the first span and represents the server-side span of the call. It took 20.4 ms.

On the right, you can see the tags that Istio provides by default.

Now you can deploy your own app and generate your own trace data. Here are instructions for uninstalling the Bookfinder app.

cacert.pem File

DST Root CA X3

Updated 4 months ago

Instrument with Istio as Your Service Mesh

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.