{"id":20317611,"url":"https://github.com/dynatrace/oneagent-sdk-for-java","last_synced_at":"2025-04-11T17:55:30.307Z","repository":{"id":54615974,"uuid":"102108040","full_name":"Dynatrace/OneAgent-SDK-for-Java","owner":"Dynatrace","description":"Enables custom tracing of Java applications in Dynatrace","archived":false,"fork":false,"pushed_at":"2024-09-03T06:48:50.000Z","size":491,"stargazers_count":35,"open_issues_count":0,"forks_count":9,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-25T13:51:11.639Z","etag":null,"topics":["agent","apm","data-ingestion","dev-program","dynatrace","oneagent","sdk","sdk-java"],"latest_commit_sha":null,"homepage":"https://www.dynatrace.com/support/help/extend-dynatrace/oneagent-sdk/what-is-oneagent-sdk/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dynatrace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-01T11:54:18.000Z","updated_at":"2025-01-23T23:27:38.000Z","dependencies_parsed_at":"2024-06-12T11:14:02.718Z","dependency_job_id":"1bfbacc9-5442-4cfe-834c-c6b191c24d91","html_url":"https://github.com/Dynatrace/OneAgent-SDK-for-Java","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dynatrace%2FOneAgent-SDK-for-Java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dynatrace%2FOneAgent-SDK-for-Java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dynatrace%2FOneAgent-SDK-for-Java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dynatrace%2FOneAgent-SDK-for-Java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dynatrace","download_url":"https://codeload.github.com/Dynatrace/OneAgent-SDK-for-Java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248456295,"owners_count":21106601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","apm","data-ingestion","dev-program","dynatrace","oneagent","sdk","sdk-java"],"created_at":"2024-11-14T18:34:12.987Z","updated_at":"2025-04-11T17:55:30.298Z","avatar_url":"https://github.com/Dynatrace.png","language":"Java","readme":"# Dynatrace OneAgent SDK for Java\n\nThis SDK allows Dynatrace customers to instrument java applications. This is useful to enhance the visibility for proprietary frameworks or\ncustom frameworks not directly supported by Dynatrace OneAgent out-of-the-box.\n\nThis is the official Java implementation of the [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK).\n\n## Table of Contents\n\n* [Package contents](#package-contents)\n* [Requirements](#requirements)\n* [Integration](#integration)\n  * [Dependencies](#dependencies)\n  * [Troubleshooting](#troubleshooting)\n* [API concepts](#api-concepts)\n  * [OneAgentSDK object](#oneagentsdk-object)\n  * [Trace Context](#tracecontext)\n  * [Tracers](#tracers)\n* [Features](#features)\n  * [Trace incoming and outgoing remote calls](#trace-incoming-and-outgoing-remote-calls)\n  * [In process linking](#in-process-linking)\n  * [Add custom request attributes](#add-custom-request-attributes)\n  * [Custom services](#custom-services)\n  * [Trace web requests](#trace-web-requests)\n    * [Trace incoming web requests](#trace-incoming-web-requests)\n    * [Trace outgoing web requests](#trace-outgoing-web-requests)\n  * [Trace messaging](#trace-messaging)\n  * [Trace SQL database requests](#trace-sql-database-requests)\n* [Further reading](#further-reading)\n* [Help \u0026 support](#help-\u0026-support)\n* [Release notes](#release-notes)\n\n## Package contents\n\n* `samples`: contains sample application, which demonstrates the usage of the SDK. See readme inside the samples directory for more details.\n* `docs`: contains the reference documentation (javadoc). The most recent version is also available online at [https://dynatrace.github.io/OneAgent-SDK-for-Java/](https://dynatrace.github.io/OneAgent-SDK-for-Java/).\n* `LICENSE`: license under which the whole SDK and sample applications are published.\n\n## Requirements\n\n* An JRE that is both supported with a supported version of OneAgent and at least JRE 1.6-compatible.\n* Dynatrace OneAgent (for required versions, see table below)\n* The OneAgent SDK is not supported on serverless code modules, including those for AWS Lambda.\n  Consider using [OpenTelemetry](https://www.dynatrace.com/support/help/shortlink/opentel-lambda)\n  instead in these scenarios.\n\n|OneAgent SDK for Java|Required OneAgent version|Support status|\n|:--------------------|:------------------------|:-------------|\n|1.9.0                |\u003e=1.261                  |Supported     |\n|1.8.0                |\u003e=1.201                  |Supported     |\n|1.7.0                |\u003e=1.167                  |Deprecated with support ending 2023-09-01 |\n|1.6.0                |\u003e=1.161                  |Deprecated with support ending 2023-09-01 |\n|1.4.0                |\u003e=1.151                  |Deprecated with support ending 2023-09-01 |\n|1.3.0                |\u003e=1.149                  |Deprecated with support ending 2023-09-01 |\n|1.2.0                |\u003e=1.147                  |Deprecated with support ending 2023-09-01 |\n|1.1.0                |\u003e=1.143                  |Deprecated with support ending 2023-09-01 |\n|1.0.3                |\u003e=1.135                  |Deprecated with support ending 2023-09-01 |\n\n## Integration\n\n### Dependencies\n\nIf you want to integrate the OneAgent SDK into your application, just add the following Maven dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.dynatrace.oneagent.sdk.java\u003c/groupId\u003e\n  \u003cartifactId\u003eoneagent-sdk\u003c/artifactId\u003e\n  \u003cversion\u003e1.9.0\u003c/version\u003e\n  \u003cscope\u003ecompile\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\nIf you prefer to integrate the SDK using plain jar file, just download them from Maven Central, e.g. from\n\u003chttps://central.sonatype.com/artifact/com.dynatrace.oneagent.sdk.java/oneagent-sdk/1.9.0/versions\u003e.\n\nThe Dynatrace OneAgent SDK for Java has no further dependencies.\n\n### Troubleshooting\n\nIf the SDK can't connect to the OneAgent (see usage of SDKState in samples) or you you don't see the desired result in the Dynatrace UI,\nyou can set the following system property to print debug information to standard out:\n\n```java\n-Dcom.dynatrace.oneagent.sdk.debug=true\n```\n\nAdditionally you should/have to ensure, that you have set a `LoggingCallback`. For usage see class `StdErrLoggingCallback` in\n`remotecall-server` module (in samples/remotecall folder).\n\n## API concepts\n\nCommon concepts of the Dynatrace OneAgent SDK are explained in the [Dynatrace OneAgent SDK repository](https://github.com/Dynatrace/OneAgent-SDK#apiconcepts).\n\n### OneAgentSDK object\n\nUse OneAgentSDKFactory.createInstance() to obtain an OneAgentSDK instance. You should reuse this object throughout the whole application\nand, if possible, JVM lifetime:\n\n```Java\nOneAgentSDK oneAgentSdk = OneAgentSDKFactory.createInstance();\nswitch (oneAgentSdk.getCurrentState()) {\ncase ACTIVE:\n  break;\ncase PERMANENTLY_INACTIVE:\n  break;\ncase TEMPORARILY_INACTIVE:\n  break;\ndefault:\n  break;\n}\n```\n\nIt is good practice to check the SDK state regularly as it may change at any point in time (except for PERMANENTLY_INACTIVE, which never\nchanges throughout the JVM lifetime).\n\n\n\u003ca name=\"tracecontext\"\u003e\u003c/a\u003e\n\n## Trace Context\n\nAn instance of the `OneAgentSDK` can be used to get the current `ITraceContextInfo` which holds information\nabout the *Trace-Id* and *Span-Id* of the current PurePath node.\nThis information can then be used to provide e.g. additional context in log messages.\n\nPlease note that `TraceContextInfo` is not intended for tagging or context-propagation use cases.\nDedicated APIs (e.g. [remote calls](#remoting) or [web requests](#webrequests)) as well as\nbuilt-in OneAgent sensors take care of linking services correctly.\n\n```Java\nTraceContextInfo traceContextInfo = oneAgentSdk.getTraceContextInfo();\nString traceId = traceContextInfo.getTraceId();\nString spanId = traceContextInfo.getSpanId();\nSystem.out.printf(\"[!dt dt.trace_id=%s,dt.span_id=%s] sending request... have trace ctx: %s%n\",\ntraceId, spanId, traceContextInfo.isValid());\n```\n\n### Tracers\n\nTo trace any kind of call you first need to create a Tracer. The Tracer object represents the logical and physical endpoint that\nyou want to call. A Tracer serves two purposes. First, to time the call (duration, cpu and more) and report errors. That is why\neach Tracer has these three methods. The error method must be called only once, and it must be in between start and end.\n\nA Tracer instance can only be used from the thread on which it was created.\nSee [in process linking](#in-process-linking) for tracing across thread boundaries, and see further below in this section\nfor how to cross process boundaries.\n\n```Java\nvoid start();\n\nvoid error(String message);\n\nvoid end();\n```\n\n`start()` records the active PurePath node on the current Java thread\nas parent (if any; whether created by another Tracer or the OneAgent), creates a new PurePath node\nand sets the new one as the currently active one. The OneAgent also requires that a child node ends\nbefore all parent nodes (Stated another way, tracers on the same thread must be ended in the opposite\norder of how they were started. While this may sound odd if you hear it the first time, it corresponds\nto the most natural usage pattern and you usually don't even need to think about it).\n\nWhile the tracer's automatic parent-child relationship works very intuitively in most cases,\nit does not work with **asynchronous patterns**, where the same thread handles multiple logically\nseparate operations in an interleaved way on the same Java thread. If you need to instrument\nsuch patterns, it is recommended to use the OneAgent's [OpenTelemetry interoperability][oa-otel].\n\n[oa-otel]: https://www.dynatrace.com/support/help/shortlink/opent-java\n\nThe second purpose of a Tracer is to allow tracing across process boundaries. To achieve that these kind of traces supply so called\ntags. Tags are strings or byte arrays that enable Dynatrace to trace a transaction end to end. As such the tag is the one information\nthat you need to transport across these calls as an SDK user.\n\n## Features\n\nThe feature sets differ slightly with each language implementation. More functionality will be added over time, see \u003ca href=\"https://answers.dynatrace.com/spaces/483/dynatrace-product-ideas/idea/198106/planned-features-for-oneagent-sdk.html\" target=\"_blank\"\u003ePlanned features for OneAgent SDK\u003c/a\u003e\nfor details on upcoming features.\n\nA more detailed specification of the features can be found in [Dynatrace OneAgent SDK](https://github.com/Dynatrace/OneAgent-SDK#features).\n\n|Feature                                        |Required OneAgent SDK for Java version|\n|:----------------------------------------------|:-------------------------------------|\n|Trace context for log enrichment               |\u003e=1.9.0                               |\n|Custom services                                |\u003e=1.8.0                               |\n|Trace database requests                        |\u003e=1.7.0                               |\n|Trace messaging                                |\u003e=1.6.0                               |\n|Outgoing web requests                          |\u003e=1.4.0                               |\n|Incoming web requests                          |\u003e=1.3.0                               |\n|Custom request attributes                      |\u003e=1.2.0                               |\n|In process linking                             |\u003e=1.1.0                               |\n|Trace incoming and outgoing remote calls       |\u003e=1.0.3                               |\n\n\n\u003ca name=\"remoting\"\u003e\u003c/a\u003e\n\n### Trace incoming and outgoing remote calls\n\nYou can use the SDK to trace proprietary IPC communication from one process to the other. This will enable you to see full Service Flow, PurePath\nand Smartscape topology for remoting technologies that Dynatrace is not aware of.\n\nTo trace any kind of remote call you first need to create a Tracer. The Tracer object represents the endpoint that you want to call, as such you\nneed to supply the name of the remote service and remote method. In addition you need to transport the tag in your remote call to the server side\nif you want to trace it end to end.\n\n```Java\nOneAgentSDK oneAgentSdk = OneAgentSDKFactory.createInstance();\nOutgoingRemoteCallTracer outgoingRemoteCall = oneAgentSdk.traceOutgoingRemoteCall(\"remoteMethodToCall\", \"RemoteServiceName\", \"rmi://Endpoint/service\", ChannelType.TCP_IP, \"remoteHost:1234\");\noutgoingRemoteCall.setProtocolName(\"RMI/custom\");\noutgoingRemoteCall.start();\ntry {\n\tString tag = outgoingRemoteCall.getDynatraceStringTag();\n\t// make the call and transport the tag across to server\n} catch (Throwable e) {\n\toutgoingRemoteCall.error(e);\n\t// rethrow or add your exception handling\n} finally {\n\toutgoingRemoteCall.end();\n}\n```\n\nOn the server side you need to wrap the handling and processing of your remote call as well. This will not only trace the server side call and\neverything that happens, it will also connect it to the calling side.\n\n```Java\nOneAgentSDK oneAgentSdk = OneAgentSDKFactory.createInstance();\nIncomingRemoteCallTracer incomingRemoteCall = oneAgentSdk.traceIncomingRemoteCall(\"remoteMethodToCall\", \"RemoteServiceName\", \"rmi://Endpoint/service\");\nincomingRemoteCall.setDynatraceStringTag(tag);\nincomingRemoteCall.start();\ntry {\n\tincomingRemoteCall.setProtocolName(\"RMI/custom\");\n\tdoSomeWork(); // process the remoteCall\n} catch (Exception e) {\n\tincomingRemoteCall.error(e);\n\t// rethrow or add your exception handling\n} finally{\n\tincomingRemoteCall.end();\n}\n```\n\n### In process linking\n\nYou can use the SDK to link inside a single process. To link for eg. an asynchronous execution, you need the following code:\n\n```Java\nOneAgentSDK oneAgentSdk = OneAgentSDKFactory.createInstance();\nInProcessLink inProcessLink = oneAgentSdk.createInProcessLink();\n```\n\nProvide the returned ``inProcessLink`` to the code, that does the asynchronous execution:\n\n```Java\nOneAgentSDK oneAgentSdk = OneAgentSDKFactory.createInstance();\nInProcessLinkTracer inProcessLinkTracer = oneAgentSdk.traceInProcessLink(inProcessLink);\ninProcessLinkTracer.start();\ntry {\n\t// do the work ...\n} catch (Exception e) {\n\tinProcessLinkTracer.error(e);\n\t// rethrow or add your exception handling\n} finally {\n\tinProcessLinkTracer.end();\n}\n```\n\n### Add custom request attributes\n\nYou can use the SDK to add custom request attributes to the current traced service. Custom request attributes allow you to do advanced filtering of\nyour requests in Dynatrace.\n\nAdding custom request attributes to the currently traced service call is simple. Just call one of the addCustomRequestAttribute methods with your key and value:\n\n```Java\noneAgentSDK.addCustomRequestAttribute(\"region\", \"EMEA\");\noneAgentSDK.addCustomRequestAttribute(\"salesAmount\", 2500);\n```\n\nWhen no service call is being traced, the custom request attributes are dropped.\n\n### Custom services\n\nYou can use the SDK to trace custom service methods. A custom service method is a meaningful\npart of your code that you want to trace but that does not fit any other tracer.\nAn example could be the callback of a periodic timer.\n\n```Java\nString serviceMethod = \"onTimer\";\nString serviceName = \"PeriodicCleanupTask\";\nCustomServiceTracer tracer = oneAgentSDK.traceCustomService(serviceMethod, serviceName);\ntracer.start();\ntry {\n\tdoMyCleanup();\n} catch (Exception e) {\n\ttracer.error(e.getMessage());\n\tthrow e;\n} finally {\n\ttracer.end();\n}\n```\n\n\u003ca name=\"webrequests\"\u003e\u003c/a\u003e\n\n### Trace web requests\n\n#### Trace incoming web requests\n\nYou can use the SDK to trace incoming web requests. This might be useful if Dynatrace does not support the respective web server framework or language\nprocessing the incoming web requests.\n\nTo trace an incoming web request you first need to create a WebApplicationInfo object. The info object represents the endpoint of your web server (web server name, application name and context root). This object should be reused for all traced web requests within for the same application.\n\n```Java\nWebApplicationInfo wsInfo = oneAgentSdk.createWebApplicationInfo(\"WebShopProduction\", \"CheckoutService\", \"/api/service/checkout\");\n```\n\nTo trace a specific incoming web request you then need to create a Tracer object. Make sure you provide all http headers from the request to the SDK by\ncalling addRequestHeader(...). This ensures that tagging with our built-in sensor will work, but note that only the proprietary x-dynatrace header\nwill be processed (meaning, W3C trace context is not supported for tracing with the OneAgent SDKs, use OpenTelemetry instead if you require this).\n\n```Java\nIncomingWebRequestTracer tracer = oneAgentSdk.traceIncomingWebRequest(wsInfo,\"https://www.oursupershop.com/api/service/checkout/save\", \"POST\")\n\nfor (Entry\u003cString, String\u003e headerField : httpRequest.getHeaders().entrySet()) {\n\ttracer.addRequestHeader(headerField.getKey(), headerField.getValue());\n}\n\nfor (Entry\u003cString, List\u003cString\u003e\u003e parameterEntry : httpRequest.getParameters().entrySet()) {\n\tfor (String value : parameterEntry.getValue()) {\n\t\ttracer.addParameter(parameterEntry.getKey(), value);\n\t}\n}\n\ntracer.setRemoteAddress(httpRequest.getRemoteHostName());\n\ntracer.start();\ntry {\n\tint statusCodeReturnedToClient = processWebRequest();\n\ttracer.setStatusCode(statusCodeReturnedToClient);\n} catch (Exception e) {\n\ttracer.setStatusCode(500); // we expect that the container sends HTTP 500 status code in case request processing throws an exception\n\ttracer.error(e);\n\tthrow e;\n} finally {\n\ttracer.end();\n}\n```\n\n#### Trace outgoing web requests\n\nYou can use the SDK to trace outgoing web requests. This might be useful if Dynatrace does not support the respective http library or\nlanguage sending the request.\n\nTo trace an outgoing web request you need to create a Tracer object. It is important to send the Dynatrace Header. This ensures that\ntagging with our built-in sensor will work.\n\n```Java\nOutgoingWebRequestTracer outgoingWebRequestTracer = oneAgentSdk.traceOutgoingWebRequest(url, \"GET\");\n\n// provide all request headers to outgoingWebRequestTracer (optional):\nfor (Entry\u003cString, String\u003e entry : yourHttpClient.getRequestHeaders().entrySet()) {\n\toutgoingWebRequestTracer.addRequestHeader(entry.getKey(), entry.getValue());\n}\n\noutgoingWebRequestTracer.start();\ntry {\n\tyourHttpClient.setUrl(url);\n\n\t// sending HTTP header OneAgentSDK.DYNATRACE_HTTP_HEADERNAME is necessary for tagging:\n\tyourHttpClient.addRequestHeader(OneAgentSDK.DYNATRACE_HTTP_HEADERNAME, outgoingWebRequestTracer.getDynatraceStringTag());\n\n\tyourHttpClient.processHttpRequest();\n\n\tfor (Entry\u003cString, List\u003cString\u003e\u003e entry : yourHttpClient.getHeaderFields().entrySet()) {\n\t\tfor (String value : entry.getValue()) {\n\t\t\toutgoingWebRequestTracer.addResponseHeader(entry.getKey(), value);\n\t\t}\n\t}\n\toutgoingWebRequestTracer.setStatusCode(yourHttpClient.getResponseCode());\n\n} catch (Exception e) {\n\toutgoingWebRequestTracer.error(e);\n\t// rethrow or add your exception handling\n} finally {\n\toutgoingWebRequestTracer.end();\n}\n```\n\n### Trace messaging\n\nYou can use the SDK to trace messages sent or received via messaging \u0026 queuing systems. When tracing messages, we distinguish between:\n\n* sending a message\n* receiving a message\n* processing a received message\n\nTo trace an outgoing message, you simply need to create a MessagingSystemInfo and call traceOutgoingMessage with that instance:\n\n```Java\nMessagingSystemInfo messagingSystemInfo = oneAgentSDK.createMessagingSystemInfo(\"myMessagingSystem\",\n\t\t\"requestQueue\", MessageDestinationType.QUEUE, ChannelType.TCP_IP, \"localhost:4711\");\nOutgoingMessageTracer outgoingMessageTracer = oneAgentSDK.traceOutgoingMessage(messagingSystemInfo);\noutgoingMessageTracer.start();\ntry {\n\t// transport the dynatrace tag along with the message: \t\n\tmessageToSend.setHeaderField(\n\t\tOneAgentSDK.DYNATRACE_MESSAGE_PROPERTYNAME, outgoingMessageTracer.getDynatraceStringTag());\n\t// optional:  add application provided correlationId\n\toutgoingMessageTracer.setCorrelationId(toSend.correlationId);\n\n\ttheQueue.send(messageToSend);\n\n\t// optional:  add messageid provided from messaging system\n\toutgoingMessageTracer.setVendorMessageId(toSend.getMessageId());\n} catch (Exception e) {\n\toutgoingMessageTracer.error(e.getMessage());\n\t// rethrow or add your exception handling\n} finally {\n\toutgoingMessageTracer.end();\n}\n```\n\nOn the incoming side, we need to differentiate between the blocking receiving part and processing the received message. Therefore two\ndifferent tracers are being used: `IncomingMessageReceiveTracer` and `IncomingMessageProcessTracer`.\n\n```Java\nMessagingSystemInfo messagingSystemInfo = oneAgentSDK.createMessagingSystemInfo(\"myMessagingSystem\",\n\t\t\"requestQueue\", MessageDestinationType.QUEUE, ChannelType.TCP_IP, \"localhost:4711\");\n\n// message receiving daemon task:\nwhile(true) {\n\tIncomingMessageReceiveTracer incomingMessageReceiveTracer =\n\t\toneAgentSDK.traceIncomingMessageReceive(messagingSystemInfo);\n\tincomingMessageReceiveTracer.start();\n\ttry {\n\t\t// blocking call - until message is being available:\n\t\tMessage queryMessage = theQueue.receive(\"client queries\");\n\t\tIncomingMessageProcessTracer incomingMessageProcessTracer = oneAgentSDK\n\t\t\t.traceIncomingMessageProcess(messagingSystemInfo);\n\t\tincomingMessageProcessTracer.setDynatraceStringTag(\n\t\t\tqueryMessage.getHeaderField(OneAgentSDK.DYNATRACE_MESSAGE_PROPERTYNAME));\n\t\tincomingMessageProcessTracer.setVendorMessageId(queryMessage.msgId);\n\t\tincomingMessageProcessTracer.setCorrelationId(queryMessage.correlationId);\n\t\tincomingMessageProcessTracer.start();\n\t\ttry {\n\t\t\t// do the work ...\n\t\t} catch (Exception e) {\n\t\t\tincomingMessageProcessTracer.error(e.getMessage());\n\t\t\tLogger.logError(e);\n\t\t} finally {\n\t\t\tincomingMessageProcessTracer.end();\n\t\t}\n\t} catch (Exception e) {\n\t\tincomingMessageReceiveTracer.error(e.getMessage());\n\t\t// rethrow or add your exception handling\n\t} finally {\n\t\tincomingMessageReceiveTracer.end();\n\t}\n}\n```\n\nIn case of non-blocking receive (e. g. via event handler), there is no need to use `IncomingMessageReceiveTracer` - just trace processing\nof the message by using the `IncomingMessageProcessTracer`:\n\n```Java\nMessagingSystemInfo messagingSystemInfo = oneAgentSDK.createMessagingSystemInfo(\"myMessagingSystem\",\n\t\"requestQueue\", MessageDestinationType.QUEUE, ChannelType.TCP_IP, \"localhost:4711\");\n\npublic void onMessage(Message message) {\n\tIncomingMessageProcessTracer incomingMessageProcessTracer = oneAgentSDK\n\t\t.traceIncomingMessageProcess(messagingSystemInfo);\n\tincomingMessageProcessTracer.setDynatraceStringTag((String)\n\t\tmessage.getObjectProperty(OneAgentSDK.DYNATRACE_MESSAGE_PROPERTYNAME));\n\tincomingMessageProcessTracer.setVendorMessageId(queryMessage.msgId);\n\tincomingMessageProcessTracer.setCorrelationId(queryMessage.correlationId);\n\tincomingMessageProcessTracer.start();\n\ttry {\n\t\t// do the work ...\n\t} catch (Exception e) {\n\t\tincomingMessageProcessTracer.error(e.getMessage());\n\t\t// rethrow or add your exception handling\n\t} finally {\n\t\tincomingMessageProcessTracer.end();\n\t}\n}\n```\n\n\u003e Please also see the [documentation on messaging tracers in the specification repository](https://github.com/Dynatrace/OneAgent-SDK#messaging).\n\n### Trace SQL database requests\n\nA SQL database request is traced by calling `traceSqlDatabaseRequest`. For details about usage see the [OneAgentSDK specification](https://github.com/Dynatrace/OneAgent-SDK#database)\n\n```java\nString sql = \"SELECT * FROM transformationdata WHERE transformation_id = \" + id;\n\nDatabaseInfo databaseInfo = oneAgentSdk.createDatabaseInfo(\"TransformationDb\", DatabaseVendor.FIREBIRD.getVendorName(), ChannelType.TCP_IP, \"db-serv01.acme.com:2323\");\n\nDatabaseRequestTracer databaseTracer = oneAgentSdk.traceSqlDatabaseRequest(databaseInfo, sql);\ndatabaseTracer.start();\ntry {\n\tResult result = executeTheDatabaseCall(sql);\n\tdatabaseTracer.setReturnedRowCount(result.getRows().getLength());\n} catch (InterruptedException e) {\n\tdatabaseTracer.error(e);\n    // handle or rethrow\n} finally {\n\tdatabaseTracer.end();\n}\n```\n\nPlease note that SQL database traces are only created if they occur within some other SDK trace (e.g. incoming remote call)\nor a OneAgent built-in trace (e.g. incoming web request).\n\n## Further reading\n\n* \u003ca href=\"https://www.dynatrace.com/support/help/extend-dynatrace/oneagent-sdk/what-is-oneagent-sdk/\" target=\"_blank\"\u003eWhat is the OneAgent SDK?\u003c/a\u003e in the Dynatrace documentation\n* \u003ca href=\"https://answers.dynatrace.com/spaces/483/dynatrace-product-ideas/idea/198106/planned-features-for-oneagent-sdk.html\" target=\"_blank\"\u003eFeedback \u0026 Roadmap thread in AnswerHub\u003c/a\u003e\n* \u003ca href=\"https://www.dynatrace.com/news/blog/dynatrace-oneagent-sdk-for-java-end-to-end-monitoring-for-proprietary-java-frameworks/\" target=\"_blank\"\u003eBlog: Dynatrace OneAgent SDK for Java: End-to-end monitoring for proprietary Java frameworks\u003c/a\u003e\n\n## Help \u0026 support\n\n### Support policy\n\nThe Dynatrace OneAgent SDK for Java has GA status. The features are fully supported by Dynatrace.\n\nFor detailed support policy see [Dynatrace OneAgent SDK help](https://github.com/Dynatrace/OneAgent-SDK#help).\n\n### Get help\n\n* Ask a question in the \u003ca href=\"https://answers.dynatrace.com/spaces/482/view.html\" target=\"_blank\"\u003eproduct forums\u003c/a\u003e\n* Read the \u003ca href=\"https://www.dynatrace.com/support/help/\" target=\"_blank\"\u003eproduct documentation\u003c/a\u003e\n\n**Open a \u003ca href=\"https://github.com/Dynatrace/OneAgent-SDK-for-Java/issues\"\u003eGitHub issue\u003c/a\u003e to:**\n\n* Report minor defects, minor items or typos\n* Ask for improvements or changes in the SDK API\n* Ask any questions related to the community effort\n\nSLAs don't apply for GitHub tickets\n\n**Customers can open a ticket on the \u003ca href=\"https://support.dynatrace.com/supportportal/\" target=\"_blank\"\u003eDynatrace support portal\u003c/a\u003e to:**\n\n* Get support from the Dynatrace technical support engineering team\n* Manage and resolve product related technical issues\n\nSLAs apply according to the customer's support level.\n\n## Release notes\n\n### Version 1.9.0\n\n* [Add support to retrieve W3C trace context information for log enrichment.](#tracecontext)\n\n### Other announcements\n\n* ⚠️ **Deprecation announcement for older SDK versions:** Version 1.7 and all older versions have been put on the path to deprecation and will no longer be supported starting September 1, 2023. We advise customers to upgrade to newest version. Customers need to upgrade to at least 1.8 but are encouraged to upgrade to the newest available version (1.9).\n\n### Older versions\n\nSee \u003chttps://github.com/Dynatrace/OneAgent-SDK-for-Java/releases\u003e for older release notes.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynatrace%2Foneagent-sdk-for-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdynatrace%2Foneagent-sdk-for-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdynatrace%2Foneagent-sdk-for-java/lists"}