Docs » Instrument applications for Splunk APM » Learn how to instrument an application with examples

Learn how to instrument an application with examples 🔗

Important

The original µAPM product, released in 2019, is now called µAPM Previous Generation (µAPM PG). Wherever you see the reference, µAPM now refers to the product released on March 31, 2020.

If you’re using µAPM Previous Generation (µAPM PG), see Overview of SignalFx Microservices APM Previous Generation (µAPM PG).

Use sample applications Splunk APM provides to learn how each instrumentation library configures automatic instrumentation for an application. Configure automatic instrumentation for a sample application to send traces to Splunk APM. View the source code of an automatically-instrumented sample application to see how instrumentation works. After you instrument an application, analyze traces for it with APM.

These steps show you how to configure and deploy the Smart Agent in a Docker container that receives trace data from a sample application you run and forwards trace data to APM.

Requirements 🔗

Requirement Description
Docker Use Docker to deploy the Smart Agent that receives trace data and forwards trace data to APM.
Port 9080 Expose port 9080 for the Smart Agent to listen for trace data from a sample application.
Git Clone the repository to get a sample application Splunk hosts on GitHub.
Access token Use an access token for your organization to send trace data to APM.

Steps 🔗

Follow these steps to configure and deploy the Smart Agent in a Docker container that receives data from a sample application.

  1. Create an agent.yaml file to specify configuration options for the Smart Agent. For more information about configuring the Smart Agent, see Agent Configuration.
# The realm for your organization.
signalFxRealm: <yourRealm>
# An available access token for your organization.
signalFxAccessToken: <yourAccessToken>
# The APM ingest endpoint for your organization.
traceEndpointUrl: "https://ingest.<yourRealm>.signalfx.com/v2/trace"
# Disable collectd.
collectd:
  disableCollectd: true
# Set up an HTTP server that listens for trace data on listenAddress.
# Because the Smart Agent runs in Docker, set the host to 0.0.0.0.
monitors:
- type: signalfx-forwarder
  listenAddress: 0.0.0.0:9080
# Specify the format to export traces in.
writer:
  traceExportFormat: sapm
  1. From the directory you saved the agent.yaml file, deploy a Docker container that runs the Smart Agent:
$ docker run --rm -p 9080:9080 -v ${PWD}/agent.yaml:/etc/signalfx/agent.yaml:ro \
 --pid host -v /:/hostfs:ro -v /var/run/docker.sock:/var/run/docker.sock:ro -v /etc/passwd:/etc/passwd:ro \
 quay.io/signalfx/signalfx-agent:5.1.3
  1. Confirm the Smart Agent is running properly. Run this curl command to send a mock trace to the Smart Agent:
$ curl -X POST "http://0.0.0.0:9080/v1/trace" -H "accept: application/json" -H "content-type: application/json" -d '[ { "id": "352bff9a74ca9ad2", "traceId": "5af7183fb1d4cf5f", "name": "get /api", "timestamp": 1556604172355737, "duration": 1431, "kind": "SERVER", "localEndpoint": { "serviceName": "backend", "ipv4": "192.168.99.1", "port": 3306 }, "remoteEndpoint": { "ipv4": "172.19.0.2", "port": 58648 }, "tags": { "http.method": "GET", "http.path": "/api" } }]'

If the Smart Agent is working as expected, you see an "OK" response.

  1. Specify the endpoint URL for the instrumentation library. Set the SIGNALFX_ENDPOINT_URL environment variable:
$ export SIGNALFX_ENDPOINT_URL=http://0.0.0.0:9080/v1/trace

The default endpoint URL is localhost, but because the Smart Agent is running in a Docker container, you have to explicitly set the endpoint URL.

  1. Deploy instrumentation and run a sample application.

Here are sample applications for instrumentation libraries. View the source code for each application to see how instrumentation is configured. Follow the steps in GitHub to run a sample application and export traces to APM.

Language Sample application Tracing library
Node.js SignalFx Tracing Library for JavaScript
.NET Core SignalFx Tracing Library for .NET Core on Linux
Go SignalFx Tracing Library for Go
PHP SignalFx Tracing Library for PHP
  1. From the user interface, select APM.
  2. Find the sample application you’re generating trace data with from the Monitoring view. You can now analyze traces for the sample application in APM.