LightStep

LightStep Documentation

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

Get Started    

Use Istio as Your Service Mesh with LightStep

Deploying on Google Kubernetes Engine

LightStep works with many service meshes, and LightStep + Istio is a particularly 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.

Prerequisites

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>.
    Use: ingest.lightstep.com:443
On-Premise Satellites
  • Satellite pool address in the format <host>:<port>.
    You find this in your configuration file.
  • Confirm that your Satellites are configured 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 ACCESS_TOKEN=[YOUR_ACCESS_TOKEN]
export ISTIO_VERSION=1.1.5
  1. Download Istio from Github.
wget https://github.com/istio/istio/releases/download/$ISTIO_VERSION/istio-$ISTIO_VERSION-osx.tar.gz
  1. Untar the archive and go to the install directory.
tar zxvf istio-$ISTIO_VERSION-osx.tar.gz

cd istio-$ISTIO_VERSION
  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 'istio.io\|certmanager.k8s.io' | wc -l
  1. Set configuration parameters in the helm template and apply to Istio.
    For LightStep Tracing and Developer Mode, use ingest.lightstep.com:443 for the value of global.tracer.lightstep.address.
    For LightStep [x]PM, use the address from your configuration file.
helm template --set pilot.traceSampling=100 --set global.proxy.tracer="lightstep" --set global.tracer.lightstep.address="ingest.lightstep.com:443" --set global.tracer.lightstep.accessToken=$ACCESS_TOKEN --set global.tracer.lightstep.secure=true --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. LightStep Tracing and Developer Mode 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[?(@.name=="http2")].port}')
export SECURE_INGRESS_PORT=$(kubectl -n istio-system get service istio-ingressgateway -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
  1. Set the GATEWAY_URL.
export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
  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
==============
-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/MSQwIgYDVQQK
ExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMTDkRTVCBSb290IENBIFgzMB4X
DTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVowPzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1
cmUgVHJ1c3QgQ28uMRcwFQYDVQQDEw5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQAD
ggEPADCCAQoCggEBAN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmT
rE4Orz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEqOLl5CjH9
UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9bxiqKqy69cK3FCxolkHRy
xXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40d
utolucbY38EVAjqr2m7xPi71XAicPNaDaeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0T
AQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQ
MA0GCSqGSIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69ikug
dB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXrAvHRAosZy5Q6XkjE
GB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZzR8srzJmwN0jP41ZL9c8PDHIyh8bw
RLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubS
fZGL+T0yjWW06XyxV3bqxbYoOb8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
-----END CERTIFICATE-----

Use Istio as Your Service Mesh with LightStep


Deploying on Google Kubernetes Engine

Suggested Edits are limited on API Reference Pages

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