mirror of
https://gitlab.com/gitlab-org/gitlab-foss.git
synced 2025-08-01 16:04:19 +00:00
Add latest changes from gitlab-org/gitlab@master
This commit is contained in:
GitLab Bot
127
doc/tutorials/observability/observability_java_tutorial.md
Normal file
127
doc/tutorials/observability/observability_java_tutorial.md
Normal file
@ -0,0 +1,127 @@
|
||||
---
|
||||
stage: Monitor
|
||||
group: Observability
|
||||
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
||||
---
|
||||
|
||||
# Tutorial: Use GitLab Observability with a Java Spring application
|
||||
|
||||
DETAILS:
|
||||
**Tier:** Ultimate
|
||||
**Offering:** GitLab.com
|
||||
**Status:** Beta
|
||||
|
||||
> - Observability [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `observability_features`. Disabled by default.
|
||||
|
||||
FLAG:
|
||||
The availability of this feature is controlled by a feature flag.
|
||||
For more information, see the history.
|
||||
This feature is available for testing, but not ready for production use.
|
||||
|
||||
In this tutorial, you'll learn how to create, configure, instrument, and monitor a Java Spring application using GitLab Observability features.
|
||||
|
||||
## Before you begin
|
||||
|
||||
To follow along this tutorial, you must have:
|
||||
|
||||
- A GitLab Ultimate subscription for GitLab.com
|
||||
- A local installation of Ruby on Rails
|
||||
- Basic knowledge of Git, Java Spring, and the core concepts of [OpenTelemetry](https://opentelemetry.io/)
|
||||
|
||||
## Create a GitLab project
|
||||
|
||||
First, create a GitLab project and a corresponding access token.
|
||||
|
||||
1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
|
||||
1. Select **Create from template**.
|
||||
1. Select **Spring** and then **Use template**.
|
||||
1. Enter the project details.
|
||||
- In the **Project name** field, enter a name such as `test-spring-o11y`
|
||||
1. Select **Create project**.
|
||||
1. In the `test-sprint-o11y` project, on the left sidebar, select **Settings > Access tokens**.
|
||||
1. Create a new access token with the Owner role and the `read_api` and `write_observability` scopes. Store the token value somewhere safe—you'll need it later.
|
||||
|
||||
## Run the application
|
||||
|
||||
Next, we'll run the application to ensure that it works.
|
||||
|
||||
1. After cloning the project from GitLab, open it in IntelliJ (or your preferred IDE).
|
||||
1. Open `src/main/java/com.example.demo/DemoApplication` and run the application:
|
||||
|
||||
1. After initialization, the application should be available at `http://localhost:8000`. Test it out, then in the IDE select the **Stop** button.
|
||||
|
||||
## Add the OpenTelemetry dependencies
|
||||
|
||||
Use auto-instrumentation to instrument the application:
|
||||
|
||||
1. In the `pom.xml` file, add the required dependencies:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-api</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-sdk-extension-autoconfigure-spi</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
```xml
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-bom</artifactId>
|
||||
<version>1.40.0</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
```
|
||||
|
||||
1. Update dependencies by selecting **Update Maven Changes**:
|
||||
|
||||
|
||||
|
||||
1. Download the OpenTelemetry java agent file from the OpenTelemetry repository.
|
||||
|
||||
```shell
|
||||
curl --location --http1.0 "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar"
|
||||
```
|
||||
|
||||
## Define environment variables
|
||||
|
||||
The OpenTelemetry autoconfigure libraries read their configuration from environment variables.
|
||||
|
||||
1. From the top-right menu, select **Edit Configurations...**:
|
||||
|
||||
|
||||
|
||||
1. In the configuration menu, select the icon in the **Environment Variables** field.
|
||||
|
||||
|
||||
|
||||
1. Add the following set of environment variables, replacing `{{PATH_TO_JAVA_AGENT}}`, `{{NAMESPACE_ID}}`, `{{PROJECT_ID}}`, `{{PROJECT_ACCESS_TOKEN}}` and `{{SERVICE_NAME}}` with the correct values.
|
||||
- `JAVA_TOOL_OPTIONS=-javaagent:{{PATH_TO_JAVA_AGENT}}/opentelemetry-javaagent.jar`
|
||||
- `OTEL_EXPORTER_OTLP_ENDPOINT=https://observe.gitlab.com/v3/{{NAMESPACE_ID}}/{{PROJECT_ID}}/ingest`
|
||||
- `OTEL_EXPORTER_OTLP_HEADERS=PRIVATE-TOKEN\={{PROJECT_ACCESS_TOKEN}}`
|
||||
- `OTEL_LOGS_EXPORTER=otlp`
|
||||
- `OTEL_METRIC_EXPORT_INTERVAL=15000`
|
||||
- `OTEL_METRICS_EXPORTER=otlp`
|
||||
- `OTEL_SERVICE_NAME=example-java-application`
|
||||
- `OTEL_TRACES_EXPORTER=otlp`
|
||||
|
||||
1. Restart the application and reload the page at `http://localhost:8000` a few times.
|
||||
|
||||
## View the information in GitLab
|
||||
|
||||
To view the exported information from your test project:
|
||||
|
||||
1. On the left sidebar, select **Search or go to** and find your project.
|
||||
1. Select **Monitor**, then either **Logs**, **Metrics**, or **Traces**.
|
||||
@ -1,127 +1,11 @@
|
||||
---
|
||||
stage: Monitor
|
||||
group: Observability
|
||||
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
|
||||
redirect_to: 'observability_java_tutorial.md'
|
||||
remove_date: '2024-10-25'
|
||||
---
|
||||
|
||||
# Tutorial: Use GitLab Observability with a Java Spring application
|
||||
This document was moved to [another location](observability_java_tutorial.md).
|
||||
|
||||
DETAILS:
|
||||
**Tier:** Ultimate
|
||||
**Offering:** GitLab.com
|
||||
**Status:** Beta
|
||||
|
||||
> - Observability [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124966) in GitLab 16.2 [with a flag](../../administration/feature_flags.md) named `observability_features`. Disabled by default.
|
||||
|
||||
FLAG:
|
||||
The availability of this feature is controlled by a feature flag.
|
||||
For more information, see the history.
|
||||
This feature is available for testing, but not ready for production use.
|
||||
|
||||
In this tutorial, you'll learn how to create, configure, instrument, and monitor a Java Spring application using GitLab Observability features.
|
||||
|
||||
## Before you begin
|
||||
|
||||
To follow along this tutorial, you must have:
|
||||
|
||||
- A GitLab Ultimate subscription for GitLab.com
|
||||
- A local installation of Ruby on Rails
|
||||
- Basic knowledge of Git, Java Spring, and the core concepts of [OpenTelemetry](https://opentelemetry.io/)
|
||||
|
||||
## Create a GitLab project
|
||||
|
||||
First, create a GitLab project and a corresponding access token.
|
||||
|
||||
1. On the left sidebar, at the top, select **Create new** (**{plus}**) and **New project/repository**.
|
||||
1. Select **Create from template**.
|
||||
1. Select **Spring** and then **Use template**.
|
||||
1. Enter the project details.
|
||||
- In the **Project name** field, enter a name such as `test-spring-o11y`
|
||||
1. Select **Create project**.
|
||||
1. In the `test-sprint-o11y` project, on the left sidebar, select **Settings > Access tokens**.
|
||||
1. Create a new access token with the Owner role and the `read_api` and `write_observability` scopes. Store the token value somewhere safe—you'll need it later.
|
||||
|
||||
## Run the application
|
||||
|
||||
Next, we'll run the application to ensure that it works.
|
||||
|
||||
1. After cloning the project from GitLab, open it in IntelliJ (or your preferred IDE).
|
||||
1. Open `src/main/java/com.example.demo/DemoApplication` and run the application:
|
||||
|
||||
1. After initialization, the application should be available at `http://localhost:8000`. Test it out, then in the IDE select the **Stop** button.
|
||||
|
||||
## Add the OpenTelemetry dependencies
|
||||
|
||||
Use auto-instrumentation to instrument the application:
|
||||
|
||||
1. In the `pom.xml` file, add the required dependencies:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-api</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-sdk-extension-autoconfigure-spi</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
```xml
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>io.opentelemetry</groupId>
|
||||
<artifactId>opentelemetry-bom</artifactId>
|
||||
<version>1.40.0</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
```
|
||||
|
||||
1. Update dependencies by selecting **Update Maven Changes**:
|
||||
|
||||
|
||||
|
||||
1. Download the OpenTelemetry java agent file from the OpenTelemetry repository.
|
||||
|
||||
```shell
|
||||
curl --location --http1.0 "https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar"
|
||||
```
|
||||
|
||||
## Define environment variables
|
||||
|
||||
The OpenTelemetry autoconfigure libraries read their configuration from environment variables.
|
||||
|
||||
1. From the top-right menu, select **Edit Configurations...**:
|
||||
|
||||
|
||||
|
||||
1. In the configuration menu, select the icon in the **Environment Variables** field.
|
||||
|
||||
|
||||
|
||||
1. Add the following set of environment variables, replacing `{{PATH_TO_JAVA_AGENT}}`, `{{NAMESPACE_ID}}`, `{{PROJECT_ID}}`, `{{PROJECT_ACCESS_TOKEN}}` and `{{SERVICE_NAME}}` with the correct values.
|
||||
- `JAVA_TOOL_OPTIONS=-javaagent:{{PATH_TO_JAVA_AGENT}}/opentelemetry-javaagent.jar`
|
||||
- `OTEL_EXPORTER_OTLP_ENDPOINT=https://observe.gitlab.com/v3/{{NAMESPACE_ID}}/{{PROJECT_ID}}/ingest`
|
||||
- `OTEL_EXPORTER_OTLP_HEADERS=PRIVATE-TOKEN\={{PROJECT_ACCESS_TOKEN}}`
|
||||
- `OTEL_LOGS_EXPORTER=otlp`
|
||||
- `OTEL_METRIC_EXPORT_INTERVAL=15000`
|
||||
- `OTEL_METRICS_EXPORTER=otlp`
|
||||
- `OTEL_SERVICE_NAME=example-java-application`
|
||||
- `OTEL_TRACES_EXPORTER=otlp`
|
||||
|
||||
1. Restart the application and reload the page at `http://localhost:8000` a few times.
|
||||
|
||||
## View the information in GitLab
|
||||
|
||||
To view the exported information from your test project:
|
||||
|
||||
1. On the left sidebar, select **Search or go to** and find your project.
|
||||
1. Select **Monitor**, then either **Logs**, **Metrics**, or **Traces**.
|
||||
<!-- This redirect file can be deleted after <2024-10-25>. -->
|
||||
<!-- Redirects that point to other docs in the same project expire in three months. -->
|
||||
<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. -->
|
||||
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
|
||||
|
||||
Reference in New Issue
Block a user