In Analytics, an event encapsulates a unit of analytics data. In APM, for example, each event corresponds to a method or service invocation, whether it be an entry point service or downstream service.

With the Analytics API, you define the structure of your own custom event in the data store, capture the event records as they occur in your custom source, and send them to the Events Service, the data store for Analytics. Once your data is in the Events Store, users can query your data through the Controller UI or the Analytics Events API.

Analytics Events API uses a shared key to authenticate clients to the Events Service. As a Controller or Analytics Administrator, you can generate API keys from the Controller UI. See Manage API Keys.

Addressing the Events Service Data Store

Unlike most Splunk AppDynamics REST APIs, which are presented at the Controller, you access the Analytics Events API by addressing the Events Service instance in the Splunk AppDynamics platform.

You address the Events Service at one of the following URLs:

You can get the Analytics Domain URLs from the SaaS Domains and IP Ranges page.

For an on-premises Events Service, address the Events Service instance host (or more likely, the virtual IP presented by a load balancer for the Events Service cluster). Use the primary default listening port for the Events Service, 9080.

Calls to the Analytics Events API need to specify the <global_account_name> or the <eum_account_name>for the Controller account being address, and the <api_key> generated by the administrator for this client. The API expects the values as headers, property-value pairs that are separated by a colon. As cURL arguments, for example, the values would be passed with curl through the `-H` or `--header option` as follows:

-H"X-Events-API-AccountName:<global_account_name> OR <eum_account_name>" -H"X-Events-API-Key:<api_key>"

You can get the global account name to use from the License page in the Controller UI. The API keys are described in Manage API Keys.

The content type, also as a cURL argument, is:

-H"Content-type: application/vnd.appd.events+json;v=2"

Splunk AppDynamics strongly recommends the use of SSL/HTTPS to access the API. Otherwise, the API key is sent in plain text.

Data Format

The Analytics Events API takes events as JSON-formatted name-value pair data.

Before sending data that conforms to a custom events schema, you need to define the data structure for the custom schema. The Events Service matches incoming events data to the appropriate schema.

Supported Data Types

• Boolean
• Date – Supported time formats include:
  • ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSSZZ .
  • UNIX epoch date format: A 13-digit number representing the number of seconds/milliseconds since UNIX epoch time (Jan 1, 1970). For example, (GMT): Mon, 17 Apr 2017 23:46:22 GMT would be 1492472782000.
• Float
• Integer
• String

Naming Restrictions

Custom event names and field names must conform to the following:

• Contain only a-z, A-Z, _ (underscore), 0-9.
• Names can not start with a number.

Timestamp Fields

Two implicit timestamp fields are automatically added to custom schemas:

• eventTimestamp
• pickupTimestamp

The eventTimestamp field represents the time an event occurred. An API client can specify a value for the timestamp field when it creates an event. If it does not, the Analytics Events API uses the same value for eventTimestamp as it uses for another implicit field, pickupTimestamp.The pickupTimestamp field, which is always populated by the Events Service, represents the time the event was received by the Events Service.

When configuring a milestone in Business Journeys, you need to supply a date in the eventTimestamp field in order for the event to register. In order to use Custom Events to define Business Journey, the custom events should send the eventTimestamp field. If not, the Business Journeys will not work.

Splunk AppDynamics uses

You can express all timestamp fields using ISO 8601 or UNIX epoch time (64-bit milliseconds) format.

Example API Call Flow

The following steps take you through an on-premises API call workflow for using the Analytics Events API. The steps show cURL examples for creating a schema, publishing an event to that schema, and then querying the event.

1. Define the schema by associating field names with data types. For example, the following defines a Purchase event type:

   curl -X POST "<events_service_endpoint>:9080/events/schema/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '{"schema" : { "id": "string", "productBrand": "string", "userRating": "integer", "price": "float", "productName": "string", "description": "string" } }'

2. Publish an event based on the schema you created:

   curl -X POST "<events_service_endpoint>:9080/events/publish/myProducts" -H"X-Events-API-AccountName:customer1_1234-567a-bccc-123" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+json;v=2" -d '[{"id": "5653b879ab33a","productBrand": "ACME","userRating": 3,"price": 2006.41,"productName": "Watch","description": "new watch"},{"id": "5653b879700","productBrand": "Widget","userRating": 1,"price": 3800.13,"productName": "Watch","description": "2015 watch"}]'

3. Query the event data:

   curl -X POST "http://<events_service_endpoint>:9080/events/query" -H"X-Events-API-AccountName:customer1_7xxx-467a-bccc-xxx" -H"X-Events-API-Key:a123b456-c789-1d23-e456-nnn" -H"Content-type: application/vnd.appd.events+text;v=2" -d 'SELECT * FROM myProducts'

If including fields with ADQL keywords, enclose the keywords in single quotes. These keywords include, for example, between, in, select, and others.

For a single query request, use this content type:

-H"Content-type: application/vnd.appd.events+text;v=2"

In a multi-query request, the queries are passed as JSON body text. In this case, use the following content type header:

-H"Content-type: application/vnd.appd.events+json;v=2"

コントローラによるカスタムイベントの取り込みには、次の制限があります。

• フィールド：イベントタイプごとに最大 255
• 文字列属性：最大長 4 KB
• バッチ総数：コールあたり 10,000 イベント
• バッチ合計サイズ：コールあたり最大 5 MB
• アカウントの最大カスタムイベントスキーマ数：20

イベントサービスでは、デフォルトで最大 1,500 個のカスタムフィールドを作成できます。カスタムフィールドの容量が 80％（1,200 フィールド）に達すると、次のインデックスロールオーバー時に最大フィールド制限が 500 フィールド増加します。

たとえば、1,400 カスタムフィールドに到達すると、最大フィールド制限が 1,500 フィールドから 2,000 フィールドに増加します。その後 1,800 カスタムフィールドに到達すると、最大制限数が 2,500 フィールドに増加します。

作成できるカスタムフィールドの上限は 3,000 個です。最大フィールド数に到達したり、最大フィールド数を超えたりすると、遅延や停止が発生する可能性があります。

Publish Events API コールは、イベントの配列を取得し、イベントサービスストレージに格納します。データは既存のスキーマに準拠している必要があります。1 つの要求を複数のイベントタイプにパブリッシュすることはできません。

イベントデータがイベントスキーマと一致しない場合、イベントサービスは両者が一致するためのベストエフォート型の試みを行い、それでも失敗した場合は「400 Bad Request」を返します。

形式

クエリパラメータ

N/A

パスパラメータ

ヘッダー

SaaS による Publish の例

リクエスト

POST https://analytics.api.example.com/events/publish/{schemaName}
X-Events-API-AccountName:<global_account_name> OR <eum_account_name>
X-Events-API-Key:<api_key>
Content-Type: application/vnd.appd.events+json;v=2 Accept: application/vnd.appd.events+json;v=2
[
{
"id": "5653b879ab33a",
"productBrand": "ACME",
"userRating": 3,
"price": 2006.41,
"productName": "Watch",
"description": "new watch"
},
{
"id": "5653b879700",
"productBrand": "Widget",
"userRating": 1,
"price": 3800.13,
"productName": "Watch",
"description": "2015 watch"
}
]

レスポンス

HTTP/1.1 202 ACCEPTED

エラー コード

独自のイベントスキーマを作成するには、この API を使用します。このスキーマで、フィールドとタイプごとにイベントタイプの全体的な構造を定義します。

この API は、アップロードするイベントが、最初のクラスイベントタイプ（ログやトランザクションなど）の既存のスキーマと一致しない場合にのみ使用する必要があります。既存のスキーマに準拠したイベントは、そのスキーマに自動的に一致します。このトピックより前に記載されている、サポートされるデータ型および命名制限を確認してください。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Create の例

既存のイベントスキーマを取得するには、この API を使用します。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Retrieve の例

フィールドごとに既存のイベントスキーマを更新するには、この API を使用します。要求本文で、イベントスキーマに適用される更新内容を定義します。

次の例に示すように、各フィールドの更新アクションを要求本文の名前付きセクションとして指定します。アクションは次のフィールドで表されます。

• 追加フィールド
• 名前変更フィールド

追加フィールドを定義する場合は、イベントスキーマを作成する場合と同じように、新しいフィールドのデータ形式を指定する必要があります。

このコールへの応答は、変更された完全なイベントスキーマである必要があります。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Update の例

既存のイベントスキーマを削除するには、この API を使用します。

形式

パスパラメータ

クエリパラメータ

N/A

ヘッダー

SaaS による Delete 要求の例

DELETE http://analytics.api.example.com/events/schema/{schemaName} HTTP/1.1
X-Events-API-AccountName:<global_account_name> OR <eum_account_name>
X-Events-API-Key:<api_key>
Accept: application/vnd.appd.events+json;v=2

分析イベントデータをクエリする場合は、次の条件が適用されます。

• すべてのイベントサービス API で、各イベントタイプのアカウントごとに 1 分あたり 200 件の検索制限があります。

• クエリが複数あるイベント API では、HTTP リクエストごとのクエリが 20 個に制限されます。

• 分析クエリ API は、最大で 1 万件の結果を返すことができます。データを超えてページを取得する場合は、スクロールモードを使用できます。スクロールモードは、バッチあたり 1,000 件の結果に制限されます。

  警告: スクロールモードは、クエリイベント（複数のクエリ）では使用できません。

• ADQL は、システムの安定性に影響を与える可能性のある大きな要求ボリュームを制御するために、次のヘッダーフィールドにレート制限を設定します。

  • X-Events-API-AccountName：1 分あたり 450 回のリクエスト。
  • X-Events-API-Key：1 分あたり 145 回のリクエスト。
• 集約クエリと非集約クエリでは、制限の動作が異なります。ADQL クエリで指定された制限値はバケットカウントの制限値として使用するため、全体の結果カウント制限値として使用することはできません。したがって、URL のパラメトリック制限が全体的な制限に使用されます。非集約クエリの場合はバケットの制限がないため、ADQL クエリで指定された制限値が行数の制限として取得され、URL のパラメトリック制限は、ADQL クエリで制限が指定されていない場合に 2 番目の選択肢となります。
  • 集約クエリの場合、返される行の合計数は URL クエリパラメータの制限によって制限され、ADQL クエリステートメント自体に指定された制限値には直接関連しません。ADQL クエリの制限値は、集約クエリのバケットカウントにのみ適用されます。
  • 非集約クエリの場合、LIMIT が SELECT ステートメントで指定されていなければ、URL クエリパラメータで指定された値が使用されます。制限クエリパラメータも存在しない場合、デフォルト値は 100 になります。

クエリイベント（単一クエリ）

この API は、単純なテキスト形式のクエリまたは JSON 形式のクエリとして使用できます。JSON 形式のクエリはコールあたり複数のクエリに対応でき、クエリイベント（複数のクエリ）で説明されます。

1 つのイベントタイプで、複数のイベントタイプに対する検索を実行できます。したがって、イベントタイプは URL パスにもクエリパラメータとしても指定されていませんが、要求本文に指定された ADQL クエリに含まれています。ADQL クエリは、 ADQL リファレンス で説明されている構文に従う必要があります。

ここでは、イベントをクエリするための単一クエリフォームについて説明します。

形式

クエリパラメータ

ヘッダー

SaaS による Query の例

クエリイベント（複数のクエリ）

特定のアカウントとイベントタイプに対し複数のクエリを並行して実行するには、この API を使用します。複数のクエリを指定するクエリイベントは、要求本文に複数の ADQL クエリを含めることで実行されます。ADQL クエリは、 ADQL リファレンス で説明されている構文に従う必要があります。

このフォームでクエリを使用すると、クエリのパフォーマンスにおいて特定のバックエンドの最適化を利用できます。時間範囲や制限などのクエリフィルタ条件は、内部クエリごとに上書きできます。

形式

パスパラメータ

なし

クエリパラメータ

ヘッダー

ペイロード

SaaS による Multiple Query の例