Skip to content

Commit

Permalink
Add gae auto-configure/auto-instrumentation sample
Browse files Browse the repository at this point in the history
  • Loading branch information
@psx95
psx95 committed May 9, 2023
1 parent fcedb2f commit f6afa44
Show file tree
Hide file tree
Showing 18 changed files with 740 additions and 0 deletions.
2 changes: 2 additions & 0 deletions examples/gae-autoinstrument-example/.gcloudignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Ignore the readme file for otel agents
src/main/webapp/WEB-INF/otelagent/README.md
2 changes: 2 additions & 0 deletions examples/gae-autoinstrument-example/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Maven Build target folder
target/
63 changes: 63 additions & 0 deletions examples/gae-autoinstrument-example/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
Google AppEngine Standard with OTel Auto-instrumentation
============================
**This sample app is a Maven project and builds separately from the rest of the rest of the examples.**

This example Java app runs on GAE standard environment and is instrumented using OpenTelemetry's [auto-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) agent.

See the [Google App Engine standard environment documentation][ae-docs] for more
detailed instructions.

The sample app uses the following -

[ae-docs]: https://cloud.google.com/appengine/docs/java/


* [Java 11](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* [Maven](https://maven.apache.org/download.cgi) (at least 3.5)
* [Google Cloud SDK](https://cloud.google.com/sdk/) (aka gcloud)
* [Google Java Logging for GAE](https://github.com/googleapis/java-logging)
* [Google Java Logging - Logback](https://github.com/googleapis/java-logging-logback)
* [Auto-Configuration for OpenTelemetry in Google Cloud](https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/tree/main/exporters/auto)

## Setup

gcloud init
gcloud auth login
gcloud config set project <your-gcp-project-id>

## Maven
### Clean Build

mvn clean package

### Running locally

mvn appengine:run

### Deploying

mvn appengine:deploy -Dapp.deploy.projectId=<your-gcp-project-id>

## About the Project

The project deploys a GAE standard application to your configured Google Cloud Project. The OpenTelemetry auto-instrumentation agent automatically collects telemetry from the running application which is autoconfigured to be exported to Google Cloud via the [auto-exporter](https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/tree/main/exporters/auto).
The telemetry data from auto-instrumentation contains traces from the application which help gain insight into individual requests made to the application, along with some useful metrics which give an insight into resource utilization and more.

By default, the logging framework used in the example is [JUL](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html), but the sample can be used with [Logback](https://logback.qos.ch/) too and has been provided with a logback configuration. To switch to Logback, just modify the Logger initialization to -
```java
import org.slf4j.Logger;

class MyClass {
// other members ...
private static final Logger logger = LoggerFactory.getLogger(SampleClass.class.getName());
// rest of the code ...
}
```

Metrics and Traces can be viewed in the Google Cloud Console for your project.

*Note: Metrics exported from the auto-exporter are prefixed with `workload.googleapis.com` - you can use this to search for generated metrics in the metrics explorer.*

*Note: Details for Google App Engine Standard runtime for Java11 can be found [here](https://cloud.google.com/appengine/docs/standard/java-gen2/java-differences).*

*Note: Log enhancer currently does not work with JUL, for better log-trace correlation and enhanced logs use Logback. It is already configured for this project and can be used with SLF4J API.*
17 changes: 17 additions & 0 deletions examples/gae-autoinstrument-example/nbactions.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<actions>
<action>
<actionName>CUSTOM-appengine:run</actionName>
<displayName>appengine:run</displayName>
<goals>
<goal>appengine:run</goal>
</goals>
</action>
<action>
<actionName>CUSTOM-appengine:deploy</actionName>
<displayName>appengine:deploy</displayName>
<goals>
<goal>appengine:deploy</goal>
</goals>
</action>
</actions>
263 changes: 263 additions & 0 deletions examples/gae-autoinstrument-example/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,263 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

<modelVersion>4.0.0</modelVersion>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>

<groupId>com.google</groupId>
<artifactId>gae-otel-demo</artifactId>

<properties>
<!-- uncomment if you wish to set your project here project- gcloud is used otherwise -->
<!-- <app.deploy.project>your-gcp-project-id</app.deploy.project> -->
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
<maven.compiler.showDeprecation>true</maven.compiler.showDeprecation>
<archiveClasses>true</archiveClasses>
</properties>

<prerequisites>
<maven>3.5</maven>
</prerequisites>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>libraries-bom</artifactId>
<version>26.13.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<!-- Compile/runtime dependencies -->
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-1.0-sdk</artifactId>
<version>2.0.13</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>jstl</groupId>
<artifactId>jstl</artifactId>
<version>1.2</version>
</dependency>

<!-- Logback support for Google Cloud Logging -->
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-logging-logback</artifactId>
</dependency>
<!-- Support for default Java Logging API -->
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-logging</artifactId>
</dependency>


<!-- Opentelemetry Dependencies for Manual Instrumentation -->
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
<version>1.25.0</version>
</dependency>

<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
<version>1.25.0</version>
</dependency>

<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-semconv</artifactId>
<version>1.25.0-alpha</version>
<scope>runtime</scope>
</dependency>

<!-- Opentelemetry Dependency from auto-instrumentation annotations -->
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-instrumentation-annotations</artifactId>
<version>1.25.0</version>
</dependency>

<!-- For enabling autoconfiguration to work with Google exporters -->
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
<version>1.25.0-alpha</version>
</dependency>

<!-- Opentelemetry MDC for LogBack -->
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-logback-mdc-1.0</artifactId>
<version>1.25.0-alpha</version>
<scope>runtime</scope>
</dependency>

<!-- Test Dependencies -->
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-testing</artifactId>
<version>1.9.98</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-api-stubs</artifactId>
<version>1.9.98</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>com.google.appengine</groupId>
<artifactId>appengine-tools-sdk</artifactId>
<version>1.9.98</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>com.google.truth</groupId>
<artifactId>truth</artifactId>
<version>0.33</version>
<scope>test</scope>
</dependency>

<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-all</artifactId>
<version>1.10.19</version>
<scope>test</scope>
</dependency>
</dependencies>

<build>
<!-- for hot reload of the web application-->
<outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
<plugins>
<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>appengine-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
</configuration>
</plugin>

<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>versions-maven-plugin</artifactId>
<version>2.3</version>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>display-dependency-updates</goal>
<goal>display-plugin-updates</goal>
</goals>
</execution>
</executions>
<configuration>
<excludes>
<exclude>javax.servlet:javax.servlet-api</exclude>
<exclude>com.google.guava:guava</exclude> <!-- avoid android version -->
</excludes>
</configuration>
</plugin>

<plugin>
<artifactId>maven-war-plugin</artifactId>
<version>3.1.0</version>
</plugin>

<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.6.1</version>
</plugin>

<plugin>
<artifactId>maven-clean-plugin</artifactId>
<version>3.0.0</version>
</plugin>

<plugin>
<artifactId>maven-install-plugin</artifactId>
<version>2.5.2</version>
</plugin>

<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.20</version>
</plugin>

<plugin>
<artifactId>maven-site-plugin</artifactId>
<version>3.6</version>
</plugin>

<plugin>
<artifactId>maven-resources-plugin</artifactId>
<version>3.0.2</version>
</plugin>

<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<version>3.1.1</version>
</plugin>

<plugin>
<groupId>com.google.cloud.tools</groupId>
<artifactId>appengine-maven-plugin</artifactId>
<version>2.4.4</version>
<configuration>
<version>1</version>
</configuration>
</plugin>

<plugin>
<artifactId>maven-enforcer-plugin</artifactId>
<version>1.4.1</version>
<executions>
<execution>
<id>enforce-maven</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<requireMavenVersion>
<version>3.5</version>
</requireMavenVersion>
<requirePluginVersions>
<message>Best Practice is to always define plugin versions!</message>
<banLatest>true</banLatest>
<banRelease>true</banRelease>
<phases>clean,deploy,verify,appengine:run,appengine:deploy,appengine:update,appengine:devappaserver,site</phases>
</requirePluginVersions>
</rules>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
Loading

0 comments on commit f6afa44

Please sign in to comment.