Getting Started
Get telemetry from a client-server app in less than 5 minutes!
In this page, you’ll learn how to set up and get tracing telemetry from a simple hello-world client-server example.
You’ll work with gRPC’s Java Quick start example, which uses gRPC to communicate between the client and server. You can work through this page even if you aren’t familiar with gRPC.
Get and run the example
First, get and run the hello-world example without instrumentation:
- Get the example code.
- Run the example: you should see the client output “Hello world”.
- Stop the server before proceeding, if it is still running.
Run the instrumented example
Next, you’ll use a Java agent to automatically instrument the client and server at launch time. While you can configure the Java agent in a number of ways, the steps below use environment variables.
- Download opentelemetry-javaagent.jar from Releases of the
opentelemetry-java-instrumentation
repo. The JAR file contains the agent and all automatic instrumentation packages.Take note of the path to the JAR file. - Set and export variables that specify the Java agent JAR and a console
trace exporter, using a notation suitable for your shell/terminal
environment — we illustrate a notation for bash-like shells:
$ export JAVA_OPTS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" $ export OTEL_TRACES_EXPORTER=logging
Important
ReplacePATH/TO
above, with your path to the JAR. - Run the server as a background process. For example, for bash-like
shells run:Note the output from the
$ ./build/install/examples/bin/hello-world-server & [otel.javaagent 2022-03-19 13:38:16:712 +0000] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.12.0 Mar 19, 2022 1:38:18 PM io.grpc.examples.helloworld.HelloWorldServer start ...
otel.javaagent
. - From the same terminal, run the client:
$ ./build/install/examples/bin/hello-world-client [otel.javaagent 2022-03-19 13:38:48:462 +0000] [main] INFO io.opentelemetry.javaagent.tooling.VersionLogger - opentelemetry-javaagent - version: 1.12.0 Mar 19, 2022 1:38:50 PM io.grpc.examples.helloworld.HelloWorldClient greet INFO: Will try to greet world ... [Trace output elided -- see below for details] Mar 19, 2022 1:38:51 PM io.grpc.examples.helloworld.HelloWorldClient greet INFO: Greeting: Hello world
- Stop the server process. For example, for bash-like shells run:
$ jobs [1]+ Running ./build/install/examples/bin/hello-world-server & $ kill %1 ... *** server shut down
At step 4, you should have seen trace output from the server and client that looks something like this (trace output is line-wrapped for convenience):
[otel.javaagent 2022-03-19 13:38:51:310 +0000] [grpc-default-executor-0] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter -
'helloworld.Greeter/SayHello' : 150407692a813ceb4e9f49a02c8b1fd0
ee15310978e6f6d3 SERVER [tracer: io.opentelemetry.grpc-1.6:1.12.0]
AttributesMap{data={net.transport=ip_tcp, rpc.grpc.status_code=0,
rpc.service=helloworld.Greeter, thread.id=16, rpc.method=SayHello,
rpc.system=grpc, net.peer.ip=127.0.0.1, thread.name=grpc-default-executor-0,
net.peer.port=44186}, capacity=128, totalAddedValues=9}
[otel.javaagent 2022-03-19 13:38:51:368 +0000] [main] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter -
'helloworld.Greeter/SayHello' : 150407692a813ceb4e9f49a02c8b1fd0
6ed56cd008f241c5 CLIENT [tracer: io.opentelemetry.grpc-1.6:1.12.0]
AttributesMap{data={net.transport=ip_tcp, net.peer.name=localhost,
rpc.grpc.status_code=0, rpc.service=helloworld.Greeter, thread.id=1,
rpc.method=SayHello, rpc.system=grpc, thread.name=main, net.peer.port=50051},
capacity=128, totalAddedValues=9}
What next?
For more:
- Run this example with another exporter for telemetry data.
- Try automatic instrumentation on one of your own apps.
- For light-weight customized telemetry, try annotations.
- Learn about manual instrumentation and try out more examples.
Last modified April 6, 2022: Ensure local page refs are local (#1282) (57664d1)