version 1.2.0

README.md

@@ -17,8 +17,12 @@ The SDK package includes
 ## Features
 
 - Trace any remote call end-to-end across processes and different programming languages.
- The SDK is compatible with other OneAgent SDKs and OneAgents in general.
 - Trace any SQL-based database call.
+- Trace incoming and outgoing web requests.
+- Trace asynchronous processing within one process.
+- Add custom request attributes to any currently traced service.
+
+When tracing incoming or outgoing calls or requests, this SDK is compatible with other OneAgent SDKs and OneAgents in general.
 
 
 ## Documentation
@@ -125,11 +129,11 @@ Instrumenting an outgoing remote call:
  /* get byte representation of tag */
  onesdk_size_t byte_tag_size = 0;
  onesdk_tracer_get_outgoing_dynatrace_byte_tag(tracer, NULL, 0, &byte_tag_size);
- void* byte_tag = NULL;
+ unsigned char* byte_tag = NULL;
  if (byte_tag_size != 0) {
- byte_tag = malloc(byte_tag_size);
+ byte_tag = (unsigned char*)malloc(byte_tag_size);
  if (byte_tag != NULL)
- onesdk_tracer_get_outgoing_dynatrace_byte_tag(tracer, byte_tag, byte_tag_size, NULL);
+ byte_tag_size = onesdk_tracer_get_outgoing_dynatrace_byte_tag(tracer, byte_tag, byte_tag_size, NULL);
  }
 
  /* ... do the actual remote call (send along `byte_tag` so the other side can continue tracing) ... */
@@ -148,8 +152,8 @@ Instrumenting an outgoing remote call:
 Instrumenting an incoming remote call:
 
 ```C
- void const* byte_tag = ...;  /* pointer to the byte tag that we received from the caller */
- onesdk_size_t byte_tag_size = ...; /* size of the byte tag that we received from the caller */
+ unsigned char const* byte_tag = ...; /* pointer to the byte tag that we received from the caller */
+ onesdk_size_t byte_tag_size = ...;  /* size of the byte tag that we received from the caller */
 
  /* create tracer */
  onesdk_tracer_handle_t const tracer = onesdk_incomingremotecalltracer_create(
@@ -287,6 +291,125 @@ And release the web application info object before shutting down the SDK:
 ```
 
 
+## Using the Dynatrace OneAgent SDK to trace outgoing web requests
+
+You can use the SDK to trace web requests sent by your application:
+
+```C
+ /* create tracer */
+ onesdk_tracer_handle_t const tracer = onesdk_outgoingwebrequesttracer_create(
+ onesdk_asciistr("http://example.org:1234/my/rest-service/resources?filter=foo"),
+ onesdk_asciistr("GET"));
+
+ /* add information about the request we're about to send */
+ onesdk_outgoingwebrequesttracer_add_request_header(tracer,
+ onesdk_asciistr("Accept-Charset"), onesdk_asciistr("utf-8"));
+ onesdk_outgoingwebrequesttracer_add_request_header(tracer,
+ onesdk_asciistr("Pragma"), onesdk_asciistr("no-cache"));
+ /* ... */
+
+ /* start tracer */
+ onesdk_tracer_start(tracer);
+
+ /* get string representation of tag */
+ onesdk_size_t string_tag_size = 0;
+ onesdk_tracer_get_outgoing_dynatrace_string_tag(tracer, NULL, 0, &string_tag_size);
+ char* string_tag = NULL;
+ if (string_tag_size != 0) {
+ string_tag = (char*)malloc(string_tag_size);
+ if (string_tag != NULL)
+ string_tag_size = onesdk_tracer_get_outgoing_dynatrace_string_tag(tracer, string_tag, string_tag_size, NULL);
+ }
+
+ /* ... actually send the HTTP request, sending along `string_tag` as an HTTP header
+ (use the macro `ONESDK_DYNATRACE_HTTP_HEADER_NAME` for the header name),
+ receive the reply and decode it ... */
+
+ /* release tag memory */
+ free(string_tag);
+
+ /* add information about the response */
+ onesdk_outgoingwebrequesttracer_add_response_header(tracer,
+ onesdk_asciistr("Transfer-Encoding"), onesdk_asciistr("chunked"));
+ onesdk_outgoingwebrequesttracer_add_response_header(tracer,
+ onesdk_asciistr("Content-Length"), onesdk_asciistr("1234"));
+ onesdk_outgoingwebrequesttracer_set_status_code(tracer, 200);
+ /* ... */
+
+ /* set error information */
+ if (something_went_wrong)
+ onesdk_tracer_error(tracer, onesdk_asciistr("error type"), onesdk_asciistr("error message"));
+
+ /* end and release tracer */
+ onesdk_tracer_end(tracer);
+```
+
+
+## Using the Dynatrace OneAgent SDK to trace asynchronous activities
+
+Many applications schedule work in some asynchronous fashion. Automatic linking of tracers will not work in such scenarios - it can only link to the innermost active tracer on the current thread.
+To link the asynchronous parts to the currently active tracer, you first have to create an in-process link:
+
+```C
+ /* create in-process link */
+ onesdk_size_t in_process_link_size = 0;
+ onesdk_inprocesslink_create(NULL, 0, &in_process_link_size);
+ unsigned char* in_process_link = NULL;
+ if (in_process_link_size != 0) {
+ in_process_link = (unsigned char*)malloc(in_process_link_size);
+ if (in_process_link != NULL)
+ in_process_link_size = onesdk_inprocesslink_create(in_process_link, in_process_link_size, NULL);
+ }
+
+ /* ... start/queue asynchronous work (send along `in_process_link` so the other side can continue tracing) ... */
+
+ /* release in-process link memory */
+ free(in_process_link);
+```
+
+Once you have the in-process link, you can create an in-process link tracer to continue tracing in another thread:
+
+```C
+ unsigned char const* in_process_link = ...; /* pointer to the in-process link */
+ onesdk_size_t in_process_link_size = ...; /* size of the in-process link */
+
+ /* create in-process link tracer */
+ onesdk_tracer_handle_t const tracer = onesdk_inprocesslinktracer_create(
+ in_process_link,
+ in_process_link_size);
+
+ /* start tracer ("activates" the in-process link) */
+ onesdk_tracer_start(tracer);
+
+ /* ... do the work - new tracers started here will be linked to wherever the in-process link was created ... */
+
+ /* end & release tracer ("deactivates" the in-process link) */
+ onesdk_tracer_end(tracer);
+```
+
+Note that you can re-use in-process links to create multiple in-process link tracers.
+
+
+## Using the Dynatrace OneAgent SDK to add custom request attributes
+
+You can add custom request attributes (key value pairs) to the currently traced service. Those attributes can then be used to e.g. search/filter requests in Dynatrace.
+To add a custom request attribute, simply call one of the `onesdk_customrequestattribute_add_{type}` functions:
+
+```C
+ /* add simple values */
+ onesdk_customrequestattribute_add_integer(onesdk_asciistr("account-id"), 42);
+ onesdk_customrequestattribute_add_float(onesdk_asciistr("service-quality"), 0.707106);
+ onesdk_customrequestattribute_add_string(onesdk_asciistr("region"), onesdk_asciistr("emea"));
+
+ /* add multiple values with the same key to create a list */
+ onesdk_customrequestattribute_add_integer(onesdk_asciistr("account-group"), 1);
+ onesdk_customrequestattribute_add_integer(onesdk_asciistr("account-group"), 2);
+ onesdk_customrequestattribute_add_integer(onesdk_asciistr("account-group"), 3);
+```
+
+This will add the custom request attributes to the currently traced service. If no tracer is active, the values will be discarded.
+
+
 ## Troubleshooting
 
 If the SDK stub cannot load or initialize the agent module (see output of sample1), you can set the SDK stub's logging level to activate logging by either
@@ -314,6 +437,7 @@ To troubleshoot SDK issues you can also use the SDK's agent logging callback - s
 
 |OneAgent SDK for C/C++|Dynatrace OneAgent|
 |:---------------------|:-----------------|
+|1.2.0 |>=1.147 |
 |1.1.0 |>=1.141 |
 |1.0.0 |>=1.133 |
 
@@ -325,7 +449,8 @@ The Dynatrace OneAgent SDK is currently in early access. Please report tickets v
 
 ## Release Notes
 
-|Version|Date |Description |
-|:------|:--------|:-----------------------------------------------------------------------------------------------------------------------|
-|1.1.0 |04.2018 |Added incoming web request tracers, added row count & round trip count for DB request tracers |
-|1.0.0 |01.2018 |Initial version |
+|Version|Description |
+|:------|:-----------------------------------------------------------------------------------------------------------------------|
+|1.2.0 |Added in-process linking, added custom request attributes, added outgoing web request tracers |
+|1.1.0 |Added incoming web request tracers, added row count & round trip count for DB request tracers |
+|1.0.0 |Initial version |

docs/annotated.html

@@ -65,6 +65,7 @@
 <div class="textblock">Here are the classes, structs, unions and interfaces with brief descriptions:</div><div class="directory">
 <table class="directory">
 <tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structonesdk__string__t.html" target="_self">onesdk_string_t</a></td><td class="desc">Represents a reference to string data in a user specified encoding </td></tr>
+<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structonesdk__stub__version__t.html" target="_self">onesdk_stub_version_t</a></td><td class="desc">Stores the stub version number </td></tr>
 </table>
 </div><!-- directory -->
 </div><!-- contents -->

docs/classes.html

@@ -65,10 +65,10 @@
 <div class="qindex"><a class="qindex" href="#letter_o">o</a></div>
 <table class="classindex">
 <tr><td rowspan="2" valign="bottom"><a name="letter_o"></a><table border="0" cellspacing="0" cellpadding="0"><tr><td><div class="ah">&#160;&#160;o&#160;&#160;</div></td></tr></table>
-</td><td></td></tr>
-<tr><td></td></tr>
-<tr><td valign="top"><a class="el" href="structonesdk__string__t.html">onesdk_string_t</a>&#160;&#160;&#160;</td><td></td></tr>
+</td><td valign="top"><a class="el" href="structonesdk__stub__version__t.html">onesdk_stub_version_t</a>&#160;&#160;&#160;</td><td></td></tr>
 <tr><td></td><td></td></tr>
+<tr><td valign="top"><a class="el" href="structonesdk__string__t.html">onesdk_string_t</a>&#160;&#160;&#160;</td><td></td><td></td></tr>
+<tr><td></td><td></td><td></td></tr>
 </table>
 <div class="qindex"><a class="qindex" href="#letter_o">o</a></div>
 </div><!-- contents -->

docs/functions.html

@@ -68,6 +68,15 @@
 <li>data
 : <a class="el" href="structonesdk__string__t.html#a4c44c8b45b15599382b921f0c3e732fb">onesdk_string_t</a>
 </li>
+<li>version_major
+: <a class="el" href="structonesdk__stub__version__t.html#ad7e4c05bc2e33cb9fbfd153a3ab4279a">onesdk_stub_version_t</a>
+</li>
+<li>version_minor
+: <a class="el" href="structonesdk__stub__version__t.html#a03bee0ac0f108ba112a6ca88f99a87eb">onesdk_stub_version_t</a>
+</li>
+<li>version_patch
+: <a class="el" href="structonesdk__stub__version__t.html#afefa0d14ecdeb503b50d563fb6b3ca32">onesdk_stub_version_t</a>
+</li>
 </ul>
 </div><!-- contents -->
 <!-- start footer part -->

docs/functions_vars.html

@@ -68,6 +68,15 @@
 <li>data
 : <a class="el" href="structonesdk__string__t.html#a4c44c8b45b15599382b921f0c3e732fb">onesdk_string_t</a>
 </li>
+<li>version_major
+: <a class="el" href="structonesdk__stub__version__t.html#ad7e4c05bc2e33cb9fbfd153a3ab4279a">onesdk_stub_version_t</a>
+</li>
+<li>version_minor
+: <a class="el" href="structonesdk__stub__version__t.html#a03bee0ac0f108ba112a6ca88f99a87eb">onesdk_stub_version_t</a>
+</li>
+<li>version_patch
+: <a class="el" href="structonesdk__stub__version__t.html#afefa0d14ecdeb503b50d563fb6b3ca32">onesdk_stub_version_t</a>
+</li>
 </ul>
 </div><!-- contents -->
 <!-- start footer part -->

docs/globals.html

@@ -136,6 +136,15 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>ONESDK_CHANNEL_TYPE_UNIX_DOMAIN_SOCKET
 : <a class="el" href="group__channels.html#ga9a942d1e02f4599f4463a68a6a1d482f">onesdk_common.h</a>
 </li>
+<li>onesdk_customrequestattribute_add_float()
+: <a class="el" href="group__custom__request__attributes.html#ga524625961e36fc2e391ec322f1f80ec9">onesdk_agent.h</a>
+</li>
+<li>onesdk_customrequestattribute_add_integer()
+: <a class="el" href="group__custom__request__attributes.html#gaa134b31e7bf82b41216a585d13afda04">onesdk_agent.h</a>
+</li>
+<li>onesdk_customrequestattribute_add_string()
+: <a class="el" href="group__custom__request__attributes.html#ga995988f69c9b1945febf5e4f3594d67f">onesdk_agent.h</a>
+</li>
 <li>ONESDK_DATABASE_VENDOR_ADABAS
 : <a class="el" href="group__database__requests.html#ga04c6a962cb9071ed5d2ed69f89f7bad4">onesdk_common.h</a>
 </li>
@@ -154,6 +163,9 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>ONESDK_DATABASE_VENDOR_COLDFUSION_IMQ
 : <a class="el" href="group__database__requests.html#ga40f8a5f949b2aa0b3bc01abf16ab84dd">onesdk_common.h</a>
 </li>
+<li>ONESDK_DATABASE_VENDOR_COUCHBASE
+: <a class="el" href="group__database__requests.html#gafa231027c5332938ab9e22b45d13b7bc">onesdk_common.h</a>
+</li>
 <li>ONESDK_DATABASE_VENDOR_DB2
 : <a class="el" href="group__database__requests.html#gaa3c4b2d2a05bc5117265b5fd8a102d47">onesdk_common.h</a>
 </li>
@@ -259,6 +271,9 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>onesdk_databaserequesttracer_set_round_trip_count()
 : <a class="el" href="group__database__requests.html#ga9c2610329a2d5fe22d26512df386fac5">onesdk_agent.h</a>
 </li>
+<li>ONESDK_DYNATRACE_HTTP_HEADER_NAME
+: <a class="el" href="group__outgoing__web__requests.html#ga20dc71536dec63bd08623989ea362bcc">onesdk_common.h</a>
+</li>
 <li>ONESDK_ERROR_AGENT_NOT_ACTIVE
 : <a class="el" href="onesdk__common_8h.html#a70f0106be18f354b041f2ee9d312ac10">onesdk_common.h</a>
 </li>
@@ -328,6 +343,12 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>onesdk_initialize()
 : <a class="el" href="group__init.html#gac3d473d2899bdb54196f864ae0ccf3eb">onesdk_init.h</a>
 </li>
+<li>onesdk_inprocesslink_create()
+: <a class="el" href="group__in__process__links.html#ga83b61a85cda88d62b5301ec02e4d1f86">onesdk_agent.h</a>
+</li>
+<li>onesdk_inprocesslinktracer_create()
+: <a class="el" href="group__in__process__links.html#ga17c58512df37441b6c4f8f36db13c8b4">onesdk_agent.h</a>
+</li>
 <li>onesdk_int32_t
 : <a class="el" href="onesdk__config_8h.html#acff8bf967021eaaaeefc001d54e565b0">onesdk_config.h</a>
 </li>
@@ -361,6 +382,18 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>onesdk_outgoingremotecalltracer_set_protocol_name()
 : <a class="el" href="group__remote__calls.html#gaef81d66474779f32f2832144dacbbd88">onesdk_agent.h</a>
 </li>
+<li>onesdk_outgoingwebrequesttracer_add_request_header()
+: <a class="el" href="group__outgoing__web__requests.html#gac47caf964b8b945cf8c3b89b98e90c7c">onesdk_agent.h</a>
+</li>
+<li>onesdk_outgoingwebrequesttracer_add_response_header()
+: <a class="el" href="group__outgoing__web__requests.html#ga5156995f4fe8f7b5212d533aec907aa1">onesdk_agent.h</a>
+</li>
+<li>onesdk_outgoingwebrequesttracer_create()
+: <a class="el" href="group__outgoing__web__requests.html#ga5e69bb9338963c0566880d1501471b0b">onesdk_agent.h</a>
+</li>
+<li>onesdk_outgoingwebrequesttracer_set_status_code()
+: <a class="el" href="group__outgoing__web__requests.html#gab28e8ae0962932d082ed8046fef7d1a0">onesdk_agent.h</a>
+</li>
 <li>onesdk_result_t
 : <a class="el" href="onesdk__config_8h.html#a76d5518cc30fddd2df8ca8d313fb79dc">onesdk_config.h</a>
 </li>
@@ -382,6 +415,9 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>onesdk_stub_free_variables()
 : <a class="el" href="group__init.html#ga57a2a52b6c6243c48243e17df2b5ee0c">onesdk_init.h</a>
 </li>
+<li>onesdk_stub_get_version()
+: <a class="el" href="group__init.html#ga5ecd84146ecce636f08a3d4cdf265b7d">onesdk_init.h</a>
+</li>
 <li>onesdk_stub_is_sdk_cmdline_arg()
 : <a class="el" href="group__init.html#ga18074c8e37227e4bfbf7165ef2b0829f">onesdk_init.h</a>
 </li>

docs/globals_defs.html

@@ -130,6 +130,9 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>ONESDK_DATABASE_VENDOR_COLDFUSION_IMQ
 : <a class="el" href="group__database__requests.html#ga40f8a5f949b2aa0b3bc01abf16ab84dd">onesdk_common.h</a>
 </li>
+<li>ONESDK_DATABASE_VENDOR_COUCHBASE
+: <a class="el" href="group__database__requests.html#gafa231027c5332938ab9e22b45d13b7bc">onesdk_common.h</a>
+</li>
 <li>ONESDK_DATABASE_VENDOR_DB2
 : <a class="el" href="group__database__requests.html#gaa3c4b2d2a05bc5117265b5fd8a102d47">onesdk_common.h</a>
 </li>
@@ -217,6 +220,9 @@ <h3><a id="index_o"></a>- o -</h3><ul>
 <li>ONESDK_DATABASE_VENDOR_VERTICA
 : <a class="el" href="group__database__requests.html#ga5f750b31a0b0c68808629d6206b16c43">onesdk_common.h</a>
 </li>
+<li>ONESDK_DYNATRACE_HTTP_HEADER_NAME
+: <a class="el" href="group__outgoing__web__requests.html#ga20dc71536dec63bd08623989ea362bcc">onesdk_common.h</a>
+</li>
 <li>ONESDK_ERROR_AGENT_NOT_ACTIVE
 : <a class="el" href="onesdk__common_8h.html#a70f0106be18f354b041f2ee9d312ac10">onesdk_common.h</a>
 </li>