Skip to content

Commit 0b6be44

Browse files
dgillingdgilling
authored
Merge pull request #70 from Moesif/dg-188536190-update-otel-docs
#188536190 Add: Docs for OTel Spans and Traces
2 parents 40a8043 + 9c2feeb commit 0b6be44

File tree

3 files changed

+93
-66
lines changed

3 files changed

+93
-66
lines changed

‎source/includes/collector-api/_actions-api.md

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44

55
**`POST https://api.moesif.net/v1/actions`**
66

7-
Log a single custom action to Moesif. An action represents something a customer performed on your website
8-
such as _Sign In_ or _Purchased Subscription_. Each action consists of an _Action Name_ and optional _Metadata_.
7+
Log a single action to Moesif.
8+
Actions represent events that occur within your application at a specific point in time. They can be tracked within your UI (such as "User Clicked Sign Up") or from your backend (such as "SMS Job Finished"). Each action consists of a required _Action Name_ and optional _Metadata_.
99

1010
<aside class="warning">
11-
Currently only the moesif-browser-js SDK supports tracking actions. If you need to track custom actions from your server, use the HTTP API directly.
11+
Actions can be tracked from your frontend app using moesif-browser-js or directly from your backend using this API.
1212
</aside>
1313

1414
**An example tracking actions using moesif-browser-js:**
@@ -82,7 +82,7 @@ moesif.track('Clicked Sign Up', {
8282
|Name|Type|Required|Description|
8383
|-----------|-----------|-----------|-----------|
8484
transaction_id | string | false | A random 36 char UUID for this event. If set, Moesif will deduplicate events using this id and ensure idempotency.
85-
action_name | string | __true__ | A recognizable name such as <i>Clicked Sign Up</i> or <i>Purchased Subscription<i>
85+
action_name | string | __true__ | A recognizable name such as <i>Clicked Sign Up</i> or <i>SMS Job Finished<i>
8686
session_token | string | false | The customer's current session token as a string.
8787
user_id | string | false | Associate this API call to a [user](#users). Typically, a real person.
8888
company_id | string | false | Associate this API call to a [company](#companies) (Required for metered billing).
@@ -98,15 +98,14 @@ request |object | __true__ | The object containing the action's request context.
9898

9999
**`POST https://api.moesif.net/v1/actions/batch`**
100100

101-
Log a batch of custom action to Moesif. An action represents something a customer performed on your website
102-
such as _Sign In_ or _Purchased Subscription_. Each action consists of an _Action Name_ and optional _Metadata_.
103-
104-
This API takes an array form of the same model defined for track single action.
105-
The maximum batch size is **12MB**. Break up larger batches.
101+
Log a batch of actions to Moesif.
102+
Actions represent events that occur within your application at a specific point in time. They can be tracked within your UI (such as "User Clicked Sign Up") or from your backend (such as "SMS Job Finished"). Each action consists of a required _Action Name_ and optional _Metadata_.
106103

104+
This API accepts an array of actions as the payload
105+
The maximum batch size is **15MB**. Break up larger batches into smaller batches.
107106

108107
<aside class="warning">
109-
Currently only the moesif-browser-js SDK supports tracking actions. if you need to track actions server-side, use the HTTP API directly.
108+
Actions can be tracked from your frontend app using moesif-browser-js or directly from your backend using this API.
110109
</aside>
111110

112111
**An example tracking actions using moesif-browser-js:**
@@ -196,7 +195,7 @@ moesif.track('Clicked Sign Up', {
196195
|Name|Type|Required|Description|
197196
|-----------|-----------|-----------|-----------|
198197
transaction_id | string | false | A random 36 char UUID for this event. If set, Moesif will deduplicate events using this id and ensure idempotency. Moesif will still deduplicate even across different size batches.
199-
action_name | string | __true__ | A recognizable name such as <i>Clicked Sign Up</i> or <i>Purchased Subscription<i>
198+
action_name | string | __true__ | A recognizable name such as <i>Clicked Sign Up</i> or <i>SMS Job Finished<i>
200199
session_token | string | false | The customer's current session token as a string.
201200
user_id | string | false | Associate this API call to a [user](#users). Typically, a real person.
202201
company_id | string | false | Associate this API call to a [company](#companies) (Required for metered billing).

‎source/includes/collector-api/_events-api.md

Lines changed: 81 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
**`POST https://api.moesif.net/v1/events`**
66

7-
Log a single API call to Moesif as an event.
8-
The request payload is a single API event containing the API request, the API response, and any custom event metadata.
7+
Log an API call to Moesif. API Calls in Moesif represent a full API operation or span (in OTel terminology).
8+
Each API call is a structured log containing the API request, the API response, start and end time, context, and any custom event metadata.
99

1010
<aside class="warning">
1111
For logging API calls at scale, most customers should integrate with one of Moesif's <a href="https://www.moesif.com/implementation">API monitoring agents</a> which instrument your API automatically and handle batching.
@@ -20,64 +20,69 @@ Replace <i>YOUR_COLLECTOR_APPLICATION_ID</i> with your real Application Id
2020
<br><br><i>Example Request</i><br>
2121
</blockquote>
2222
```json
23-
{
23+
{
2424
"request": {
25-
"time": "2024-10-30T04:45:42.914",
26-
"uri": "https://api.acmeinc.com/items/12345/reviews/",
27-
"verb": "POST",
28-
"api_version": "1.1.0",
29-
"ip_address": "61.48.220.123",
30-
"headers": {
31-
"Host": "api.acmeinc.com",
32-
"Accept": "*/*",
33-
"Connection": "Keep-Alive",
34-
"Content-Type": "application/json",
35-
"Content-Length": "126",
36-
"Accept-Encoding": "gzip"
37-
},
38-
"body": {
39-
"items": [
40-
{
41-
"direction_type": 1,
42-
"item_id": "hello",
43-
"liked": false
44-
},
45-
{
46-
"direction_type": 2,
47-
"item_id": "world",
48-
"liked": true
49-
}
50-
]
51-
},
52-
"transfer_encoding": ""
25+
"time": "2024-10-30T04:45:42.914",
26+
"uri": "https://api.acmeinc.com/items/12345/reviews/",
27+
"verb": "POST",
28+
"api_version": "1.1.0",
29+
"ip_address": "61.48.220.123",
30+
"headers": {
31+
"Host": "api.acmeinc.com",
32+
"Accept": "*/*",
33+
"Connection": "Keep-Alive",
34+
"Content-Type": "application/json",
35+
"Content-Length": "126",
36+
"Accept-Encoding": "gzip"
37+
},
38+
"body": {
39+
"items": [
40+
{
41+
"direction_type": 1,
42+
"item_id": "hello",
43+
"liked": false
44+
},
45+
{
46+
"direction_type": 2,
47+
"item_id": "world",
48+
"liked": true
49+
}
50+
]
51+
},
52+
"transfer_encoding": ""
5353
},
5454
"response": {
55-
"time": "2024-10-30T04:45:42.914",
56-
"status": 500,
57-
"headers": {
58-
"Vary": "Accept-Encoding",
59-
"Pragma": "no-cache",
60-
"Expires": "-1",
61-
"Content-Type": "application/json; charset=utf-8",
62-
"Cache-Control": "no-cache"
63-
},
64-
"body": {
65-
"Error": "InvalidArgumentException",
66-
"Message": "Missing field location"
67-
},
68-
"transfer_encoding": ""
55+
"time": "2024-10-30T04:45:42.914",
56+
"status": 500,
57+
"headers": {
58+
"Vary": "Accept-Encoding",
59+
"Pragma": "no-cache",
60+
"Expires": "-1",
61+
"Content-Type": "application/json; charset=utf-8",
62+
"Cache-Control": "no-cache"
63+
},
64+
"body": {
65+
"Error": "InvalidArgumentException",
66+
"Message": "Missing field location"
67+
},
68+
"transfer_encoding": ""
6969
},
7070
"user_id": "12345",
7171
"company_id": "67890",
7272
"transaction_id": "a3765025-46ec-45dd-bc83-b136c8d1d257",
73+
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
74+
"span": {
75+
"id": "00f067aa0ba902b7",
76+
"parent_span_id": "b3c3f3c3f3c3f3c3"
77+
},
7378
"metadata": {
7479
"some_string": "I am a string",
7580
"some_int": 77,
7681
"some_object": {
77-
"some_sub_field": "some_value"
82+
"some_sub_field": "I am another string"
7883
}
7984
}
80-
}
85+
}
8186
```
8287

8388
```shell
@@ -597,7 +602,7 @@ $event->request = array(
597602
"time" => $rspdate->format(DateTime::ISO8601),
598603
"status" => 500,
599604
"headers" => array(
600-
"Date" => "Tue, 1 Mar 2022 23:46:49 GMT",
605+
"Date" => "Tue, 1 Oct 2024 23:46:49 GMT",
601606
"Vary" => "Accept-Encoding",
602607
"Pragma" => "no-cache",
603608
"Expires" => "-1",
@@ -642,12 +647,21 @@ response |object | false | The object that specifies the API response. The respo
642647
<p style="margin-left:1.5em">body</p> |object | false | Payload of the response in either JSON or a base64 encoded string.
643648
<p style="margin-left:1.5em">transfer_encoding</p> | string | false | Specifies the transfer encoding of _response.body_ field. If set to _json_ then the response.body must be a JSON object. If set to _base64_, then _response.body_ must be a base64 encoded string. Helpful for binary payloads. If not set, the body is assumed to be _json_.
644649
||
650+
span |object | false | The object that contains open telemetry span context
651+
<p style="margin-left:1.5em">id</p> |string | false | The open telemetry span id for this API call.
652+
<p style="margin-left:1.5em">parent_id</p> |string | false | The parent span id that comes before this API call.
653+
<p style="margin-left:1.5em">links</p> |array | false | List of links to related traces or spans
654+
<p style="margin-left:1.5em">status</p> |integer | false | The status of the span's operation
655+
||
656+
action_name | string | false | A recognizable operation name such as <i>Get Items</i> or <i>Triggered SMS Job<i>
657+
trace_id | string | false | The open telemetry trace_id that this API call is part of.
645658
transaction_id | string | false | A random 36 char UUID for this event. If set, Moesif will deduplicate events using this id and ensure idempotency.
646659
session_token | string | false | Set the API key/session token used for this API call. Moesif will auto-detect API sessions if not set.
647660
user_id | string | false | Associate this API call to a [user](#users). Typically, a real person.
648661
company_id | string | false | Associate this API call to a [company](#companies) (Required for metered billing).
649662
subscription_id | string | false | Associate this API call to a specific [subscription](#subscriptions) of a company. Not needed unless same company can have multiple subscriptions to the same plan. When set, usage will be reported to only this subscription.
650-
direction | string | false | The direction of this API call which can be _Incoming_ or _Outgoing_.
663+
direction | string | false | The direction of this API call which can be _Incoming_, _Outgoing_, or _Internal_
664+
weight|integer | 1 | The weight of this event which is 1/sampling rate. Moesif uses this to reweigh scalar values, like counts, ensuring they are accurate even when API calls are sampled.
651665
metadata | object | false | An object containing any custom event metadata you want to store with this event.
652666

653667

@@ -656,10 +670,10 @@ metadata | object | false | An object containing any custom event metadata you w
656670
**`POST https://api.moesif.net/v1/events/batch`**
657671

658672
Creates and logs a batch of API calls to Moesif.
659-
The request payload is an array API calls entities, each consisting of the API request, the API response, and any custom event metadata.
660-
661-
This API takes a list form of the same model defined in create single event.
673+
API Calls in Moesif represent a full API operation or span (in OTel terminology).
674+
Each API call is a structured log containing the API request, the API response, start and end time, context, and any custom event metadata.
662675

676+
This API accepts an array of API calls as the payload
663677
The maximum batch size is **50MB**. Break up larger batches into smaller batches.
664678

665679
<aside class="info">
@@ -722,6 +736,11 @@ Replace <i>YOUR_COLLECTOR_APPLICATION_ID</i> with your real Application Id
722736
"user_id": "12345",
723737
"company_id": "67890",
724738
"transaction_id": "a3765025-46ec-45dd-bc83-b136c8d1d257",
739+
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
740+
"span": {
741+
"id": "00f067aa0ba902b7",
742+
"parent_span_id": "b3c3f3c3f3c3f3c3"
743+
},
725744
"metadata": {
726745
"some_string": "I am a string",
727746
"some_int": 77,
@@ -1204,10 +1223,19 @@ response |object | false | The object that specifies the API response. The respo
12041223
<p style="margin-left:1.5em">body</p> |object | false | Payload of the response in either JSON or a base64 encoded string.
12051224
<p style="margin-left:1.5em">transfer_encoding</p> | string | false | Specifies the transfer encoding of _response.body_ field. If set to _json_ then the response.body must be a JSON object. If set to _base64_, then _response.body_ must be a base64 encoded string. Helpful for binary payloads. If not set, the body is assumed to be _json_.
12061225
||
1226+
span |object | false | The object that contains open telemetry span context
1227+
<p style="margin-left:1.5em">id</p> |string | false | The open telemetry span id for this API call.
1228+
<p style="margin-left:1.5em">parent_id</p> |string | false | The parent span id that comes before this API call.
1229+
<p style="margin-left:1.5em">links</p> |array | false | List of links to related traces or spans
1230+
<p style="margin-left:1.5em">status</p> |integer | false | The status of the span's operation
1231+
||
1232+
action_name | string | false | A recognizable operation name such as <i>Get Items</i> or <i>Triggered SMS Job<i>
1233+
trace_id | string | false | The open telemetry trace_id that this API call is part of.
12071234
transaction_id | string | false | A random 36 char UUID for this event. If set, Moesif will deduplicate events using this id and ensure idempotency. Moesif will still deduplicate even across different size batches.
12081235
session_token | string | false | Set the API key/session token used for this API call. Moesif will auto-detect API sessions if not set.
12091236
user_id | string | false | Associate this API call to a [user](#users). Typically, a real person.
12101237
company_id | string | false | Associate this API call to a [company](#companies) (Required for metered billing).
12111238
subscription_id | string | false | Associate this API call to a specific [subscription](#subscriptions) of a company. Not needed unless same company can have multiple subscriptions to the same plan. When set, usage will be reported to only this subscription.
1212-
direction | string | false | The direction of this API call which can be _Incoming_ or _Outgoing_.
1239+
direction | string | false | The direction of this API call which can be _Incoming_, _Outgoing_, or _Internal_
1240+
weight|integer | 1 | The weight of this event which is 1/sampling rate. Moesif uses this to reweigh scalar values, like counts, ensuring they are accurate even when API calls are sampled.
12131241
metadata | object | false | An object containing any custom event metadata you want to store with this event.

‎source/index.html.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ code_clipboard: true
3838

3939
# Moesif API Reference
4040

41-
Moesif is an API analytics and monetization service to grow your API products. With Moesif, you can quickly get started with API observability, API monetization and usage-based billing.
41+
Moesif is an API analytics and monetization service to build and grow better API products. With Moesif, you can quickly get started with API observability, API monetization and usage-based billing.
4242

4343
With Moesif, you cam This reference is for v1 of the Moesif APIs.
4444
For an overview on the Moesif platform, see the [developer docs](/docs) or [implementation guides](https://www.moesif.com/implementation)
@@ -52,6 +52,6 @@ There are two APIs:
5252

5353
## API definitions
5454

55-
The _Collector API_ enables you to log raw data to Moesif at high volume such as events and user profiles. It's a write-only, high-volume data collection network and is also used by the Moesif server integrations and plugins.
55+
The _Collector API_ enables you to log your raw event data to Moesif at high volume such as API calls and user profiles. It's a write-only, high-volume data collection network and is also used by the Moesif server integrations and plugins.
5656

5757
The _Management API_ enables you to query and manage data in your Moesif account such as to embed charts in customer-facing applications.

0 commit comments

Comments
 (0)