diff --git a/content/guides/http/java/_index.md b/content/guides/http/java/_index.md new file mode 100644 index 00000000..360d1577 --- /dev/null +++ b/content/guides/http/java/_index.md @@ -0,0 +1,11 @@ +--- +title: "Java" +date: 2019-02-04T00:25:17-08:00 +draft: false +class: "integration-page" +aliases: [/integrations/http/java] +logo: /images/java.png +--- + +OpenCensus Java provides integrations for the following Java HTTP frameworks: +{{% children %}} diff --git a/content/guides/http/java/jetty/_index.md b/content/guides/http/java/jetty/_index.md new file mode 100644 index 00000000..902bf7c6 --- /dev/null +++ b/content/guides/http/java/jetty/_index.md @@ -0,0 +1,20 @@ +--- +title: "Jetty" +date: 2019-02-04T00:25:17-08:00 +draft: false +class: "integration-page" +aliases: [/integrations/http/java/jetty] +logo: /images/jetty-header-logo.png +--- + +Jetty is a popular Java HTTP framework from the Eclipse foundation https://www.eclipse.org/jetty/ + +OpenCensus is integrated with Jetty, for the following parts: + +{{% children %}} + +### References + +Resource|URL +---|--- +Jetty project|https://www.eclipse.org/jetty/documentation/ diff --git a/content/guides/http/java/jetty/client.md b/content/guides/http/java/jetty/client.md new file mode 100644 index 00000000..f0da4f12 --- /dev/null +++ b/content/guides/http/java/jetty/client.md @@ -0,0 +1,407 @@ +--- +title: "Client" +date: 2019-02-04T00:35:17-08:00 +draft: false +aliases: [/integrations/http/java/jetty/client] +logo: /images/jetty-header-logo.png +--- + +- [Introduction](#introduction) +- [Imports](#imports) + - [Dependency management](#dependency-management) +- [Initializing the client](#initializing-the-client) +- [Enabling observability](#enabling-observability) + - [Stats](#stats) + - [Traces](#traces) + - [Extracing observability](#extracting-observability) +- [End-to-end example](#end-to-end-example) + - [Source code](#source-code) + - [Running it](#running-it) +- [Examining your traces](#examining-your-traces) + - [All traces](#all-traces) + - [Existent page](#existent-page) + - [Non-existent page](#non-existent-page) +- [Examining your stats](#examining-your-stats) +- [References](#references) + +### Introduction + +The Jetty client integration has been instrumented with OpenCensus and it provides traces and stats. +This integration was added in OpenCensus-Java version 0.19.1. + +### Imports + +To add the Jetty client integration, we'll perform the following import. + +{{}} +import io.opencensus.contrib.http.jetty.client.OcJettyHttpClient; +{{}} + +#### Dependency management +Please add these lines to a pom.xml file in your current working directory. + +{{}} +{{}} + + + io.opencensus + opencensus-contrib-http-jetty-client + ${opencensus.version} + + + + org.eclipse.jetty + jetty-client + ${jetty.version} + + + + io.netty + netty-tcnative-boringssl-static + 2.0.8.Final + runtime + + +{{}} +{{}} + +### Initializing the client + +The client can be initialized simply by +{{}} +package io.opencensus.tutorials.jetty; + +import io.opencensus.contrib.http.jetty.client.OcJettyHttpClient; + +public class JettyClient { + public static void main(String[] args) { + OcJettyHttpClient httpClient = new OcJettyHttpClient(); + + try { + httpClient.start(); + } catch (Exception e) { + System.err.println("Failed to start the Jetty Http client " + e); + return; + } + } +} +{{}} + +### Enabling observability + +Enabling observability takes just a few steps: + +#### Stats +To add stats, we'll just add an extra step of registering HttpViews like this + +{{}} +import io.opencensus.contrib.http.util.HttpViews; + +public class JettyClient { + private static void registerHttpViews() { + HttpViews.registerAllClientViews(); + } +} +{{}} + +and after this we'll ensure that we add any of the [Stats exporters](/exporters/supported-exporters/java) + +#### Traces +You don't need do anything else, except enable [Trace exporters](/exporters/supported-exporters/java) + +#### Extracting observability + +For the purposes of this demo, we'll do the following: + +* Enable and use the Prometheus stats exporter to extract stats +* Enable and use the Zipkin tracing exporter to extract traces +* Turn up the trace sampling rate to 100% only to ensure every run produces traces and isn't sampled + +### End to end example +{{% notice tip %}} +For assistance running any of the backends for any of the exporters, please refer to: + +Exporter|URL +---|--- +Prometheus|[Prometheus codelab](/codelabs/prometheus) +Zipkin|[Zipkin codelab](/codelabs/zipkin) +{{% /notice %}} + +In this example, we'll be fetching from two different URLs: + +URL|Purpose +---|--- +https://opencensus.io/community|Existent URL +https://opencensus.io/non-existent|Non-existent URL + +{{}} +{{}} +package io.opencensus.tutorials.jetty; + +import io.opencensus.contrib.http.jetty.client.OcJettyHttpClient; +import io.opencensus.contrib.http.util.HttpViews; +import io.opencensus.exporter.stats.prometheus.PrometheusStatsCollector; +import io.opencensus.exporter.trace.zipkin.ZipkinTraceExporter; +import io.opencensus.trace.Tracing; +import io.opencensus.trace.config.TraceConfig; +import io.opencensus.trace.samplers.Samplers; +import io.prometheus.client.exporter.HTTPServer; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import org.eclipse.jetty.client.HttpRequest; +import org.eclipse.jetty.client.api.ContentResponse; + +public class JettyClient { + public static void main(String[] args) { + + // First things first, enable observability exporters. + try { + enableOpenCensusExporters(); + } catch (Exception e) { + System.err.println("Failed to create the OpenCensus exporters: " + e); + return; + } + + OcJettyHttpClient httpClient = new OcJettyHttpClient(); + + try { + httpClient.start(); + } catch (Exception e) { + System.err.println("Failed to start the Jetty Http client " + e); + return; + } + + for (int i = 1; i <= 1000; i++) { + System.out.println("Iteration: #" + i); + + String[] urls = {"https://opencensus.io/community", "https://opencensus.io/non-existent"}; + + for (String url : urls) { + System.out.println("Fetching URL: " + url); + // Perform the synchronous request. + HttpRequest syncRequest = (HttpRequest) httpClient.newRequest(url); + try { + ContentResponse response = syncRequest.send(); + + byte[] payload = response.getContent(); + String strPayload = new String(response.getContent(), StandardCharsets.UTF_8); + System.out.println("Payload \n" + strPayload); + + System.out.println("\n\n\nNow sleeping for 5s"); + Thread.sleep(5000); + + } catch (java.lang.InterruptedException e) { + System.err.println("This thread was interrupted: " + e); + } catch (java.util.concurrent.TimeoutException e) { + System.err.println("The request timed out unfortunately: " + e); + } catch (java.util.concurrent.ExecutionException e) { + System.err.println("Execution failed: " + e); + } catch (Exception e) { + System.err.println("Unhandled exception: " + e); + } + } + } + } + + private static void enableOpenCensusExporters() throws IOException { + // Firstly enable stats from the Http client views. + HttpViews.registerAllClientViews(); + + // Register the Prometheus stats collector aka "exporter". + PrometheusStatsCollector.createAndRegister(); + HTTPServer prometheusServer = new HTTPServer(8889, true); + + // Update the trace sampling rate to 100% aka "AlwaysSample". + TraceConfig traceConfig = Tracing.getTraceConfig(); + traceConfig.updateActiveTraceParams( + traceConfig.getActiveTraceParams().toBuilder().setSampler(Samplers.alwaysSample()).build()); + + // Enable the Zipkin trace exporter. + ZipkinTraceExporter.createAndRegister( + "http://localhost:9411/api/v2/spans", "jetty-client-tutorial"); + } +} +{{}} +{{}} + + 4.0.0 + io.opencensus.tutorials.jetty + jetty-client-tutorial + jar + 0.0.1 + jettyclient + http://maven.apache.org + + + UTF-8 + 0.19.1 + + 9.4.12.v20180830 + + + + + io.opencensus + opencensus-contrib-http-jetty-client + ${opencensus.version} + + + + org.eclipse.jetty + jetty-client + ${jetty.version} + + + + io.netty + netty-tcnative-boringssl-static + 2.0.8.Final + runtime + + + + io.opencensus + opencensus-api + ${opencensus.version} + + + + io.opencensus + opencensus-impl + ${opencensus.version} + + + + io.opencensus + opencensus-exporter-stats-prometheus + ${opencensus.version} + + + + io.prometheus + simpleclient_httpserver + 0.4.0 + + + + io.opencensus + opencensus-exporter-trace-zipkin + ${opencensus.version} + + + + + + + kr.motd.maven + os-maven-plugin + 1.5.0.Final + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.7.0 + + 1.8 + 1.8 + + + + + + + + org.codehaus.mojo + appassembler-maven-plugin + 1.10 + + + + SQLApp + io.opencensus.tutorials.jetty.JettyClient + + + + + + + +{{}} +{{}} + +### Running it + +With Zipkin running as per [End-to-end example](#end-to-end-example) and Prometheus installed, the last +step is to turn on Prometheus with this configuration file that we'll save in `prom.yaml` + +{{}} +scrape_configs: + - job_name: 'jetty_tutorial' + + scrape_interval: 5s + + static_configs: + - targets: ['localhost:8889'] +{{}} + +and then run Prometheus like this + +```shell +prometheus --config.file=prom.yaml +``` + +And finally to run the code + +{{}} +mvn install && mvn exec:java -Dexec.mainClass=io.opencensus.tutorials.jetty.JettyClient +{{}} + +### Examining your traces + +On navigating to the Zipkin UI at http://localhost:9411/zipkin, you should see + +#### All traces +* All traces +![](/images/jetty-client-traces-all.png) + +#### Existent page +* On clicking on one of the spans where we fetched an existent page "https://opencensus.io/community" +![](/images/jetty-client-traces-200.png) + +#### Non-Existent page +* On clicking on one of the spans where we fetched a non-existent page "https://opencensus.io/non-existent" +![](/images/jetty-client-traces-404.png) + +### Examining your stats + +On navigating to the Prometheus UI at http://localhost:9090, you should see + +#### All stats +![](/images/jetty-client-stats-all.png) + +#### Roundtrip latency +* 95th percentile for HTTP client roundtrip latency grouped by the "http_client_status" tag +```shell +histogram_quantile(0.95, + sum(rate(opencensus_io_http_client_roundtrip_latency_bucket[5m])) by (http_client_status, le)) +``` +![](/images/jetty-client-stats-roundtrip-latency-95th.png) + +#### Sent bytes + +* Rate of sent bytes +```shell +rate(opencensus_io_http_client_sent_bytes_bucket[5m]) +``` +![](/images/jetty-client-stats-sent-bytes-rate.png) + +### References + +Resource|URL +---|--- +Jetty client JavaDoc|[org.eclipse.jetty.client](https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/client/package-summary.html) +OcJettyClient, the Jetty OpenCensus client integration|[io.opencensus.contrib.http.jetty.client.OcJettyHttpClient](https://www.javadoc.io/doc/io.opencensus/opencensus-contrib-http-jetty-client/) diff --git a/static/images/jetty-client-stats-all.png b/static/images/jetty-client-stats-all.png new file mode 100644 index 00000000..5dd616b0 Binary files /dev/null and b/static/images/jetty-client-stats-all.png differ diff --git a/static/images/jetty-client-stats-roundtrip-latency-95th.png b/static/images/jetty-client-stats-roundtrip-latency-95th.png new file mode 100644 index 00000000..19cbef24 Binary files /dev/null and b/static/images/jetty-client-stats-roundtrip-latency-95th.png differ diff --git a/static/images/jetty-client-stats-sent-bytes-rate.png b/static/images/jetty-client-stats-sent-bytes-rate.png new file mode 100644 index 00000000..09ba7fd5 Binary files /dev/null and b/static/images/jetty-client-stats-sent-bytes-rate.png differ diff --git a/static/images/jetty-client-traces-200.png b/static/images/jetty-client-traces-200.png new file mode 100644 index 00000000..28333be9 Binary files /dev/null and b/static/images/jetty-client-traces-200.png differ diff --git a/static/images/jetty-client-traces-404.png b/static/images/jetty-client-traces-404.png new file mode 100644 index 00000000..2fb79d1f Binary files /dev/null and b/static/images/jetty-client-traces-404.png differ diff --git a/static/images/jetty-client-traces-all.png b/static/images/jetty-client-traces-all.png new file mode 100644 index 00000000..8883f593 Binary files /dev/null and b/static/images/jetty-client-traces-all.png differ diff --git a/static/images/jetty-header-logo.png b/static/images/jetty-header-logo.png new file mode 100644 index 00000000..5f1b1e0b Binary files /dev/null and b/static/images/jetty-header-logo.png differ