SWO Extensibility

The SWO Platform is built for extensibility!

One of the most useful tools the Platform provides is the ability to easily push 3rd party custom events via a REST API we call Change Events. These events may be optionally associated with an existing entity - and then viewed on that entity’s health timeseries visualization. Under the covers, these events are processed in the SWO ingestion pipeline and stored as OTEL-native events.

Let’s say you’d like to push an event to SWO whenever your service is successfully deployed to one of your environments. We’ll use a service from our SWO demo application in this example: swopper-cart.

First, you’ll want to grab an Ingestion API Token from the Settings > API Tokens page and include it the the Authorization header. To associate this event with your service, we provide a header: X-Otel-Resource-Attr. You can include one or more comma-delimited entity K/Vs as the value. The format for a SWO entity key is sw.entity.<entity-type>.id. So in this case, the header will look like “X-Otel-Resource-Attr: sw.entity.service.id=e-1234567891011121314"

Next, you’ll want to obtain the SWO entity identifier for the service, which you can do from the URL of the Service Details page. Entity IDs take the format: e-1234567891011121314. The URL for our swopper-cart Service Details page is

https://$HOST/175119513436437504/entities/services/e-1631489365473914880/overview

And here’s an example curl command for sending an event called test.deploy.success indicating that for the swopper-cart v56 service was successfully deployed to the prod environment. It also includes important links to the related image update and Github PR. A command like this could be handy in build scripts in order to correlate deployments with entity health decline.

curl -X POST "https://$HOST/v1/changeevents" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $APITOKEN" \
-H "X-Otel-Resource-Attr: sw.entity.service.id=e-1631489365473914880" \
--data '{
"name": "test.deploy.success",
"title": "v56 deployed",
"source": "swopper-cart",
"description": "v56 - Fixed typo in page titles",
"tags": {"environment": "prod"},
"links": [{"rel": "ECR", "href": "915014598477.dkr.ecr.us-east-1.amazonaws.com/swopper/cart:0.1.3", "label": "Image Update" }, { "rel": "github", "href": "https://github.com/appoptics/appoptics-api-ruby", "label": "Image Update 0.1.3"}]
}'

Once your entity-associated Change Events are received by the SWO Platform, they should appear as data points on the corresponding entity Health Score timeseries chart.