From e9486abcfde0082e6dec8ea94d260d7192cb7ec8 Mon Sep 17 00:00:00 2001 From: Romain Grecourt Date: Tue, 19 Feb 2019 13:47:53 -0800 Subject: [PATCH] docs overview page, reworked intro page (#418) * docs overview page, reworked intro page * update sitegen version to 1.0.8 --- docs/src/main/docs/about/01_introduction.adoc | 75 ------------- docs/src/main/docs/about/01_overview.adoc | 102 ++++++++++++++++++ docs/src/main/docs/about/02_introduction.adoc | 62 +++++++++++ docs/src/main/docs/guides/01_overview.adoc | 1 - docs/src/main/docs/sitegen.yaml | 2 +- docs/src/main/docs/tracing/01_tracing.adoc | 59 ++++++++++ docs/src/main/docs/tracing/02_zipkin.adoc | 89 +++++++++++++++ pom.xml | 2 +- 8 files changed, 314 insertions(+), 78 deletions(-) delete mode 100644 docs/src/main/docs/about/01_introduction.adoc create mode 100644 docs/src/main/docs/about/01_overview.adoc create mode 100644 docs/src/main/docs/about/02_introduction.adoc create mode 100644 docs/src/main/docs/tracing/01_tracing.adoc create mode 100644 docs/src/main/docs/tracing/02_zipkin.adoc diff --git a/docs/src/main/docs/about/01_introduction.adoc b/docs/src/main/docs/about/01_introduction.adoc deleted file mode 100644 index 4571e7391..000000000 --- a/docs/src/main/docs/about/01_introduction.adoc +++ /dev/null @@ -1,75 +0,0 @@ -/////////////////////////////////////////////////////////////////////////////// - - Copyright (c) 2018 Oracle and/or its affiliates. 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. - -/////////////////////////////////////////////////////////////////////////////// - -= Introduction -:description: about Helidon -:keywords: helidon, java, microservices, microprofile - -== Introduction - -Helidon is a collection of Java libraries for writing microservices. -There is no unique tooling or deployment model. Your microservice is -just a Java SE application. - -The foundation of Helidon is composed of three components: - -[PILLARS] -==== - -[CARD] -.WebServer -[icon=settings_ethernet] --- -A programmatic HTTP API with reactive features, powered by Netty. --- - -[CARD] -.Config -[icon=settings] --- -A flexible configuration framework with support for multiple sources and formats. --- - -[CARD] -.Security -[icon=security] --- -A tool-chain to handle authentication, authorization and context propagation. --- -==== - -== MicroProfile - -On top of this foundation Helidon supports the MicroProfile family of APIs, - including JAX-RS and CDI. This means you can choose from one of two - programming models: - - * Helidon SE: a functional programming style that uses the Helidon WebServer, - Config and Security APIs directly. This gives you full - transparency and control. - * Helidon MP: a more declarative model that supports the https://microprofile.io[MicroProfile] - family of APIs. This will be familiar to Java EE developers. - -Our <> gets -you started using either of these programming models. - -=== Docker and Kubernetes support - -The <> contain -support for Docker and Kubernetes. Just follow the examples and you'll have -a simple service up and running in minutes. diff --git a/docs/src/main/docs/about/01_overview.adoc b/docs/src/main/docs/about/01_overview.adoc new file mode 100644 index 000000000..61c66be2c --- /dev/null +++ b/docs/src/main/docs/about/01_overview.adoc @@ -0,0 +1,102 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2019 Oracle and/or its affiliates. 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. + +/////////////////////////////////////////////////////////////////////////////// + += Overview +:description: Helidon documentation +:keywords: helidon, java, microservices, microprofile, documentation + +== Get going + +[PILLARS] +==== +[CARD] +.Getting Started +[icon=assistant,link=getting-started/02_base-example.adoc] +-- +Quickly create your first application, in under 2 minutes. +-- + +[CARD] +.Guides +[icon=explore,link=guides/01_overview.adoc] +-- +Follow step-by-step guides to build your applications. +-- +==== + +== Components + +[PILLARS] +==== +[CARD] +.WebServer +[icon=settings_ethernet,link=webserver/01_introduction.adoc] +-- +A programmatic HTTP API with reactive features, powered by Netty. +-- + +[CARD] +.Config +[icon=settings,link=config/01_introduction.adoc] +-- +A flexible configuration framework with support for multiple sources and + formats. +-- + +[CARD] +.Security +[icon=security,link=security/01_introduction.adoc] +-- +A tool-chain to handle authentication, authorization and context propagation. +-- + +[CARD] +.MicroProfile +[icon=widgets,link=microprofile/01_introduction.adoc] +-- +A platform definition that is familiar to enterprise Java developers. +-- + +[CARD] +.Extensions +[icon=extension,link=extensions/01_overview.adoc] +-- +A set of add-ons for your Helidon-based applications. +-- + +[CARD] +.Metrics +[icon=av_timer,link=metrics/01_metrics.adoc] +-- +Instrumentation to expose metrics of your applications. +-- + +[CARD] +.Tracing +[icon=timeline,link=tracing/01_tracing.adoc] +-- +Profile and monitor your applications across multiple services. +-- + +[CARD] +.Health Checks +[icon=favorite_outline,link=health/01_health.adoc] +-- +Expose health statuses of your applications. +-- +==== diff --git a/docs/src/main/docs/about/02_introduction.adoc b/docs/src/main/docs/about/02_introduction.adoc new file mode 100644 index 000000000..852abbc7a --- /dev/null +++ b/docs/src/main/docs/about/02_introduction.adoc @@ -0,0 +1,62 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2018, 2019 Oracle and/or its affiliates. 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. + +/////////////////////////////////////////////////////////////////////////////// + += Introduction +:description: about Helidon +:keywords: helidon, java, microservices, microprofile + +== A collection of Java libraries + +Helidon is a collection of Java libraries for writing microservices. + +There's no need for any specific tooling or deployment model. Simply use your + favorite tools ! + +NOTE: Your microservice is a plain Java application. You do not need an + application server. + +== Cloud-native Java + +Helidon libraries interoperate with popular tools from the cloud-native space: + +* https://www.docker.com/[Docker] +* https://kubernetes.io/[Kubernetes] +* https://prometheus.io/[Prometheus] +* https://opentracing.io/[OpenTracing] +* https://coreos.com/etcd/[Etcd] + +TIP: The <> + contain support for Docker and Kubernetes. + +== Helidon SE + +Helidon SE is the functional programming style provided by all Helidon + libraries. + +NOTE: Helidon SE gives you full transparency and puts you in control. There is + no magic! + +== Helidon MP + +Helidon MP is our MicroProfile implementation. + +https://microprofile.io[MicroProfile] is a platform definition that is familiar + to enterprise Java developers. It provides a declarative programming style that + is portable. It includes popular Java APIs such as `JAX-RS` and `CDI`. + +NOTE: Helidon MP is built on top of the Helidon libraries. \ No newline at end of file diff --git a/docs/src/main/docs/guides/01_overview.adoc b/docs/src/main/docs/guides/01_overview.adoc index 88ef2d0bb..967842f75 100644 --- a/docs/src/main/docs/guides/01_overview.adoc +++ b/docs/src/main/docs/guides/01_overview.adoc @@ -24,7 +24,6 @@ [PILLARS] ==== - [CARD] .SE REST Web Service [link=guides/02_SE_REST_web-service.adoc] diff --git a/docs/src/main/docs/sitegen.yaml b/docs/src/main/docs/sitegen.yaml index 5bdc0e62e..0b0ae114b 100644 --- a/docs/src/main/docs/sitegen.yaml +++ b/docs/src/main/docs/sitegen.yaml @@ -42,7 +42,7 @@ pages: - "**/*.adoc" backend: name: "vuetify" - homePage: "about/01_introduction.adoc" + homePage: "about/01_overview.adoc" releases: - "${project.version}" navigation: diff --git a/docs/src/main/docs/tracing/01_tracing.adoc b/docs/src/main/docs/tracing/01_tracing.adoc new file mode 100644 index 000000000..70e5a0606 --- /dev/null +++ b/docs/src/main/docs/tracing/01_tracing.adoc @@ -0,0 +1,59 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2019 Oracle and/or its affiliates. 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. + +/////////////////////////////////////////////////////////////////////////////// + += Tracing +:description: Helidon Tracing Support += :keywords: helidon, tracing + +== Tracing Support +Helidon includes support for tracing through the `https://opentracing.io/[OpenTracing]` APIs. +Tracing is integrated with WebServer and Security. + +Support for specific tracers is abstracted. Your application can depend on +the abstraction layer and provide a specific tracer implementation as a Java +`ServiceLoader` service. + + +=== Maven Coordinates + +Declare the following dependency in your project to use the tracer abstraction: + +[source,xml,subs="verbatim,attributes"] +.Tracer Abstraction +---- + + io.helidon.tracing + helidon-tracing + +---- + +=== Configuring Tracing + +To configure tracer with WebServer: + +[source,java] +.Configuring OpenTracing `Tracer` +---- +ServerConfiguration.builder() + .tracer(TracerBuilder.create("my-application") // <1> + .collectorUri(URI.create("http://10.0.0.18:9411")) // <2> + .build()) + .build() +---- +<1> The name of the application (service) to associate with the tracing events +<2> The endpoint for tracing events, specific to the tracer used, usually loaded from Config diff --git a/docs/src/main/docs/tracing/02_zipkin.adoc b/docs/src/main/docs/tracing/02_zipkin.adoc new file mode 100644 index 000000000..73f64488a --- /dev/null +++ b/docs/src/main/docs/tracing/02_zipkin.adoc @@ -0,0 +1,89 @@ +/////////////////////////////////////////////////////////////////////////////// + + Copyright (c) 2019 Oracle and/or its affiliates. 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. + +/////////////////////////////////////////////////////////////////////////////// + += Zipkin Tracing +:description: Helidon Tracing Support +:keywords: helidon, tracing + +Helidon is integrated with the Zipkin tracer. + +The Zipkin builder is loaded through `ServiceLoader` and configured. You could +also use the Zipkin builder directly, though this would create a source-code dependency +on the Zipkin tracer. + + +== Prerequisites +To use Zipkin as a tracer, + add the following dependency to your project: + +[source,xml,subs="verbatim,attributes"] +---- + + io.helidon.tracing + helidon-tracing-zipkin + +---- + +== Configuring Zipkin + +The Zipkin tracer supports the following configuration options: + +|=== +|Key |Default value |Builder method |Description + +|service |N/A |serviceName |Name of the service, to distinguish traces crossing service boundaries; + Zipkin is using lower-case only, name will be automatically lower-cased +|protocol |http |collectorProtocol |Protocol of the Zipkin trace collector (http or https) +|host |localhost |collectorHost |Host of the Zipkin trace collector (IP Address, hostname, or FQDN) +|port |9411 |collectorPort |Port of the Zipkin trace collector +|path |defined by version |collectorPath |Path of the Zipkin trace collector, each version uses a different path + by default. +|api-version |2 |version |Zipkin specific method, set the protocol version to communicate with + trace collector +|enabled |true |enabled |If set to false, tracing would be disabled +|tags |N/A |addTracerTag(String, String) |`String` tags to add to each span +|boolean-tags |N/A |addTracerTag(String, boolean)|`boolean` tags to add to each span +|int-tags |N/A |addTracerTag(String, int) |`int` tags to add to each span +|=== + +The following is an example of a Zipkin configuration, specified in the YAML format. +[source,yaml] +---- +tracing: + zipkin: + service: "helidon-service" + protocol: "https" + host: "192.168.1.1" + port: 9987 + api-version: 1 + # this is the default path for API version 1 + path: "/api/v1/spans" + tags: + tag1: "tag1-value" + tag2: "tag2-value" + boolean-tags: + tag3: true + tag4: false + int-tags: + tag5: 145 + tag6: 741 +---- + +Example of Zipkin trace: + +image::webserver/zipkin.png[Zipkin example, align="center"] diff --git a/pom.xml b/pom.xml index 131304b0c..68ff17b91 100644 --- a/pom.xml +++ b/pom.xml @@ -187,7 +187,7 @@ 2.7 3.0.0 3.7.1 - 1.0.7 + 1.0.8 3.0.1 3.1.3.1 1.0.0