Moesif OpenTelemetry Integration

Integrate Moesif API Analytics with your OpenTelemetry-instrumented applications to gain deep insights into your API traffic and performance. This integration allows you to send trace data from your OpenTelemetry setup directly to Moesif without any code changes or redeployments.

How it works

The integration works by configuring your OpenTelemetry exporter to send trace data to Moesif using the OTLP/HTTP protocol. Moesif treats each OpenTelemetry HTTP Request/Response Span as an API event, capturing key information like request and response details, user identification, and metadata.

By integrating with OpenTelemetry, you can leverage existing distributed tracing to analyze API performance and user behavior across services and applications.

How to Install

Prerequisites

An application instrumented with OpenTelemetry SDKs or an OpenTelemetry Collector which can export OTLP/HTTP.
A Moesif account.

Steps

Configure the OpenTelemetry Exporter

Set up your OpenTelemetry SDK to export trace data to Moesif using the OTLP/HTTP protocol.

Example Configuration (YAML):
```
exporters:
  otlphttp:
    endpoint: https://api.moesif.net/v1/traces
    headers:
      X-Moesif-Application-Id: 'Your Moesif Application ID'
```
Example Configuration (Environment Variables):
```
# Set the OTLP endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.moesif.net/v1/traces

# Include your Moesif Application ID in the headers
export OTEL_EXPORTER_OTLP_HEADERS=X-Moesif-Application-Id=Your_Moesif_Application_ID
```
Replace 'Your Moesif Application ID' with your actual Moesif Application ID. To get your Application ID:
1. Log into Moesif Portal.
2. Select the account icon to bring up the settings menu.
3. Select Installation or API Keys.
4. Copy your Moesif Application ID from the Collector Application ID field.
Set Up Authentication

Ensure your Moesif Application ID is included in the request headers as X-Moesif-Application-Id to authenticate requests.
Run Your Application

Start your application, and OpenTelemetry will begin sending trace data to Moesif.

Overview of Span Mapping

Moesif supports capturing HTTP request span data which follows the OpenTelemetry Semantic Conventions for HTTP Spans

Moesif maps OpenTelemetry spans to its API event model. Each span is treated as a single API event in Moesif with the addition of Trace ID, Span ID, Parent Span, Span Links, and metadata.

The HTTP semantic conventions for OpenTelemetry are recently stable. We do our best to be backward compatible with prior HTTP tracing implementations as well. To understand exactly how OpenTelemetry spans are mapped to Moesif API events, refer to the table below.

Span to Moesif API Event Mapping

OpenTelemetry Span Field	Moesif Field	Notes
`trace_id`	`trace_id`	Used to group spans into a single trace.
`span_id`	`span.id`	Unique identifier for the span.
`parent_span_id`	`span.parent_id`	Identifier of the parent span, if any.
`name`	`action_name`	Name of the span or the API action.
`kind`	`direction`	Mapped to incoming or outgoing based on span kind.
`start_time_unix_nano`	`request.time`	Start time of the request.
`end_time_unix_nano`	`response.time`	End time of the response.
`attributes`	Various fields (see below)	Attributes are mapped to Moesif fields and metadata.
`status`	`span.status`	Status of the span.

Span Attributes Mapping

OpenTelemetry span attributes are mapped to Moesif fields as follows:

Span Attribute Key	Moesif Field	Notes
`http.method`	`request.verb`	HTTP method (GET, POST, etc.).
`http.url` or `url.full`	`request.uri`	Full request URI.
`http.status_code`	`response.status`	HTTP response status code.
`http.request.header.<key>`	`request.headers.<key>`	Request headers.
`http.response.header.<key>`	`response.headers.<key>`	Response headers.
`user.id`	`user_id`	Identifier for the user.
`client.address` or `net.peer.ip`	`request.ip_address`	Client IP address.
`user_agent.original`	`request.user_agent_string`	User agent string.
`company.id`	`company_id`	Identifier for the company.

Custom Span Attributes

All other span attributes are stored in the metadata field in Moesif. You can use Span attributes to add custom metadata to your API events.

Enabling User & Company Tracking

Associate API calls with companies by adding a user.id attribute:

Span.current().setAttribute("user.id", "user_123");

Associate API calls with companies by adding a company.id attribute:

Span.current().setAttribute("company.id", "company_abc");

There are additional user and company tracking options available in Moesif. For more information, refer to the docs on Identifying Users

Example Integrations

If you are using an OpenTelemetry Collector already, the integration will be as simple as including the exporter configuration above.

If you are instrumenting an application from scratch for OpenTelemetry tracing, we have an example Node JS application that demonstrates how to set up OpenTelemetry with Moesif. The example application is available at

Node JS Tracing Example on Github

Limitations

There are certain OpenTelemetry specific limitations to be aware of:

API Body Fields Are Not Captured, OpenTelemetry does not capture request and response bodies as of this release
Traces and HTTP Spans, Only Traces, not OpenTelemetry Logs or Metrics, are supported. Within Traces, HTTP Spans are supported. Spans for other types of information cannot be ingested at this release. See OpenTelemetry Semantic Conventions for HTTP Spans
Governance Rules Are Not Supported, Moesif’s governance features, such as blocking or modifying API calls, are not supported through the OpenTelemetry integration.
Dynamic Sampling, Moesif’s dynamic sampling is not applied to data ingested via OpenTelemetry. Sampling must be configured manually within your OpenTelemetry tooling. See the OpenTelemetry Sampling Documentation

Troubleshooting

Data Not Appearing in Moesif

Ensure your OpenTelemetry exporter is correctly configured with the Moesif endpoint and Application ID and that your traces include HTTP spans.
Authentication Errors

Verify that the X-Moesif-Application-Id header is correctly set with your valid Moesif Application ID.
Incomplete Data

If certain fields are missing, check that you have correctly added custom span attributes where necessary.