-
Notifications
You must be signed in to change notification settings - Fork 4
/
openapi.json
30641 lines (30641 loc) · 882 KB
/
openapi.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{
"openapi": "3.0.1",
"info": {
"contact": {
"email": "[email protected]",
"name": "© Instana",
"url": "http://instana.com"
},
"termsOfService": "https://www.instana.com/terms-of-use/",
"title": "Introduction to Instana public APIs",
"version": "1.263.856",
"x-logo": {
"altText": "instana logo",
"backgroundColor": "#FAFBFC",
"url": "header-logo.svg"
},
"description": "Searching for answers and best pratices? Check our [IBM Instana Community](https://community.ibm.com/community/user/aiops/communities/community-home?CommunityKey=58f324a3-3104-41be-9510-5b7c413cc48f).\n\n## Agent REST API\n### Event SDK REST Web Service\nUsing the Event SDK REST Web Service, it is possible to integrate custom health checks and other event sources into Instana. Each one running the Instana Agent can be used to feed in manual events. The agent has an endpoint which listens on `http://localhost:42699/com.instana.plugin.generic.event` and accepts the following JSON via a POST request:\n\n```json\n{\n \"title\": <string>,\n \"text\": <string>,\n \"severity\": <integer> , -1, 5 or 10\n \"timestamp\": <integer>, timestamp in milliseconds from epoch\n \"duration\": <integer>, duration in milliseconds\n}\n```\n\n*Title* and *text* are used for display purposes.\n\n*Severity* is an optional integer of -1, 5 and 10. A value of -1 or EMPTY will generate a Change. A value of 5 will generate a *warning Issue*, and a value of 10 will generate a *critical Issue*.\n\nWhen absent, the event is treated as a change without severity. *Timestamp* is the timestamp of the event, but it is optional, in which case the current time is used. *Duration* can be used to mark a timespan for the event. It also is optional, in which case the event will be marked as \"instant\" rather than \"from-to.\"\n\nThe endpoint also accepts a batch of events, which then need to be given as an array:\n\n```json\n[\n {\n // event as above\n },\n {\n // event as above\n }\n]\n```\n\n#### Ruby Example\n\n```ruby\nduration = (Time.now.to_f * 1000).floor - deploy_start_time_in_ms\npayload = {}\npayload[:title] = 'Deployed MyApp'\npayload[:text] = 'pglombardo deployed MyApp@revision'\npayload[:duration] = duration\n\nuri = URI('http://localhost:42699/com.instana.plugin.generic.event')\nreq = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')\nreq.body = payload.to_json\nNet::HTTP.start(uri.hostname, uri.port) do |http|\n http.request(req)\nend\n```\n\n#### Curl Example\n\n```bash\ncurl -XPOST http://localhost:42699/com.instana.plugin.generic.event -H \"Content-Type: application/json\" -d '{\"title\":\"Custom API Events \", \"text\": \"Failure Redeploying Service Duration\", \"duration\": 5000, \"severity\": -1}'\n```\n\n#### PowerShell Example\n\nFor Powershell you can either use the standard Cmdlets `Invoke-WebRequest` or `Invoke-RestMethod`. The parameters to be provided are basically the same.\n\n```bash\nInvoke-RestMethod\n -Uri http://localhost:42699/com.instana.plugin.generic.event\n -Method POST\n -Body '{\"title\":\"PowerShell Event \", \"text\": \"You used PowerShell to create this event!\", \"duration\": 5000, \"severity\": -1}'\n```\n\n```bash\nInvoke-WebRequest\n -Uri http://localhost:42699/com.instana.plugin.generic.event\n -Method Post\n -Body '{\"title\":\"PowerShell Event \", \"text\": \"You used PowerShell to create this event!\", \"duration\": 5000, \"severity\": -1}'\n```\n### Trace SDK REST Web Service\nUsing the Trace SDK REST Web Service, it is possible to integrate Instana into any application regardless of language. Each active Instana Agent can be used to feed manually captured traces into the Web Service, which can be joined with automatically captured traces or be completely separate. The Agent offers an endpoint that listens on `http://localhost:42699/com.instana.plugin.generic.trace` and accepts the following JSON via a POST request:\n\n```json\n{\n \"spanId\": <string>,\n \"parentId\": <string>,\n \"traceId\": <string>,\n \"timestamp\": <64 bit long>,\n \"duration\": <64 bit long>,\n \"name\": <string>,\n \"type\": <string>,\n \"error\": <boolean>,\n \"data\": {\n <string> : <string>\n }\n}\n```\n\nspanId is the unique identifier for any particular span. The trace is defined by a root span, that is, a span that does not have a parentId. The traceId needs to be identical for all spans that belong to the same trace, and is allowed to be overlapping with a spanId. traceId, spanId and parentId are 64-bit unique values encoded as hex string like b0789916ff8f319f. Spans form a hierarchy by referencing the spanId of the parent as parentId. An example of a span hierarchy in a trace is shown below:\n\n```text\n root (spanId=1, traceId=1, type=Entry)\n child A (spanId=2, traceId=1, parentId=1, type=Exit)\n child A (spanId=3, traceId=1, parentId=2, type=Entry)\n child B (spanId=4, traceId=1, parentId=3, type=Exit)\n child B (spanId=5, traceId=1, parentId=4, type=Entry)\n```\n\nThe timestamp and duration fields are in milliseconds. The timestamp must be the epoch timestamp coordinated to Coordinated Universal Time.\n\nThe name field can be any string that is used to visualize and group traces, and can contain any text. However, simplicity is recommended.\n\nThe type field is optional, when absent is treated as ENTRY. Options are ENTRY, EXIT, INTERMEDIATE, or EUM. Setting the type is important for the UI. It is assumed that after an ENTRY, child spans are INTERMEDIATE or EXIT. After an EXIT an ENTRY should follow. This is visualized as a remote call.\n\nThe data field is optional and can contain arbitrary key-value pairs. The behavior of supplying duplicate keys is unspecified.\n\nThe error field is optional and can be set to true to indicate an erroneous span.\n\nThe endpoint also accepts a batch of spans, which then need to be given as an array:\n\n```json\n[\n {\n // span as above\n },\n {\n // span as above\n }\n]\n```\n\nFor traces received via the Trace SDK Web Service the same rules regarding [Conversion and Service/Endpoint Naming](https://www.ibm.com/docs/en/obi/current?topic=references-java-trace-sdk#conversion-and-naming) are applied as for the Java Trace SDK. In particular these key-value pairs in data are used for naming: service, endpoint and call.name.\n\nNote: The optional [Instana Agent Service](https://www.ibm.com/docs/en/obi/current?topic=requirements-installing-host-agent-kubernetes#instana-agent-service) provided on Kubernetes via the Instana Agent Helm Chart is very useful in combination with the Trace Web SDK support, as it ensures that the data is pushed to the Instana Agent running on the same Kubernetes node, ensuring the Instana Agent can correctly fill in the infrastructure correlation data.\n\n#### Curl Example\n\nThe following example shows how to send to the host agent data about a matching ENTRY and EXIT call, which simulates a process that receives an HTTP GET request targeted to the https://orders.happyshop.com/my/service/asdasd URL and routes it to an upstream service at the https://crm.internal/orders/asdasd URL.\n\n```bash\n#!/bin/bash\n\ncurl -0 -v -X POST 'http://localhost:42699/com.instana.plugin.generic.trace' -H 'Content-Type: application/json; charset=utf-8' -d @- <<EOF\n[\n {\n \"spanId\": \"8165b19a37094800\",\n \"traceId\": \"1368e0592a91fe00\",\n \"timestamp\": 1591346182000,\n \"duration\": 134,\n \"name\": \"GET /my/service/asdasd\",\n \"type\": \"ENTRY\",\n \"error\": false,\n \"data\": {\n \"http.url\": \"https://orders.happyshop.com/my/service/asdasd\",\n \"http.method\": \"GET\",\n \"http.status_code\": 200,\n \"http.path\": \"/my/service/asdasd\",\n \"http.host\": \"orders.happyshop.com\"\n }\n },\n {\n \"spanId\": \"7ddf6b31b320cc00\",\n \"parentId\": \"8165b19a37094800\",\n \"traceId\": \"1368e0592a91fe00\",\n \"timestamp\": 1591346182010,\n \"duration\": 97,\n \"name\": \"GET /orders/asdasd\",\n \"type\": \"EXIT\",\n \"error\": false,\n \"data\": {\n \"http.url\": \"https://crm.internal/orders/asdasd\",\n \"http.method\": \"GET\",\n \"http.status_code\": 200,\n \"http.path\": \"/orders/asdasd\",\n \"http.host\": \"crm.internal\"\n }\n }\n]\nEOF\n```\n\n#### Limitations\n\nAdhere to the following rate limits for the trace web service:\n\n- Maximum API calls/sec: 20 \n- Maximum payload per POST request: A span must not exceed 4 KiB. The request size must not exceed 4 MiB. \n- Maximum batch size (spans/array): 1000 \n\n## Backend REST API\nThe Instana API allows retrieval and configuration of key data points. Among others, this API enables automatic reaction and further analysis of identified incidents as well as reporting capabilities.\n\nThe API documentation refers to two crucial parameters that you need to know about before reading further:\n\n- `base`: This is the base URL of a tenant unit, e.g. `https://test-example.instana.io`. This is the same URL that is used to access the Instana user interface.\n- `apiToken`: Requests against the Instana API require valid API tokens. An initial API token can be generated via the Instana user interface. Any additional API tokens can be generated via the API itself.\n\n### Example\nHere is an Example to use the REST API with Curl. First lets get all the available metrics with possible aggregations with a GET call.\n\n```bash\ncurl --request GET \\\n --url https://test-instana.instana.io/api/application-monitoring/catalog/metrics \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx'\n```\n\nNext we can get every call grouped by the endpoint name that has an error count greater then zero. As a metric we could get the mean error rate for example.\n\n```bash\ncurl --request POST \\\n --url https://test-instana.instana.io/api/application-monitoring/analyze/call-groups \\\n --header 'authorization: apiToken xxxxxxxxxxxxxxxx' \\\n --header 'content-type: application/json' \\\n --data '{\n \"group\":{\n \"groupbyTag\":\"endpoint.name\"\n },\n \"tagFilters\":[\n \t{\n \t\t\"name\":\"call.error.count\",\n \t\t\"value\":\"0\",\n \t\t\"operator\":\"GREATER_THAN\"\n \t}\n ],\n \"metrics\":[\n \t{\n \t\t\"metric\":\"errors\",\n \t\t\"aggregation\":\"MEAN\"\n \t}\n ]\n }'\n```\n\n\n### Rate Limiting\nA rate limit is applied to API usage. Up to 5,000 calls per hour can be made. How many remaining calls can be made and when this call limit resets, can inspected via three headers that are part of the responses of the API server.\n\n**X-RateLimit-Limit:** Shows the maximum number of calls that may be executed per hour.\n\n**X-RateLimit-Remaining:** How many calls may still be executed within the current hour.\n\n**X-RateLimit-Reset:** Time when the remaining calls will be reset to the limit. For compatibility reasons with other rate limited APIs, this date is not the date in milliseconds, but instead in seconds since 1970-01-01T00:00:00+00:00.\n\n## Generating REST API clients\n\nThe API is specified using the [OpenAPI v3](https://github.com/OAI/OpenAPI-Specification) (previously known as Swagger) format.\nYou can download the current specification at our [GitHub API documentation](https://instana.github.io/openapi/openapi.yaml).\n\nOpenAPI tries to solve the issue of ever-evolving APIs and clients lagging behind. Please make sure that you always use the latest version of the generator, as a number of improvements are regularly made.\nTo generate a client library for your language, you can use the [OpenAPI client generators](https://github.com/OpenAPITools/openapi-generator).\n\n### Go\nFor example, to generate a client library for Go to interact with our backend, you can use the following script; mind replacing the values of the `UNIT_NAME` and `TENANT_NAME` environment variables using those for your tenant unit:\n\n```bash\n#!/bin/bash\n\n### This script assumes you have the `java` and `wget` commands on the path\n\nexport UNIT_NAME='myunit' # for example: prod\nexport TENANT_NAME='mytenant' # for example: awesomecompany\n\n//Download the generator to your current working directory:\nwget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.jar -O openapi-generator-cli.jar --server-variables \"tenant=${TENANT_NAME},unit=${UNIT_NAME}\"\n\n//generate a client library that you can vendor into your repository\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g go \\\n -o pkg/instana/openapi \\\n --skip-validate-spec\n\n//(optional) format the Go code according to the Go code standard\ngofmt -s -w pkg/instana/openapi\n```\n\nThe generated clients contain comprehensive READMEs, and you can start right away using the client from the example above:\n\n```go\nimport instana \"./pkg/instana/openapi\"\n\n// readTags will read all available application monitoring tags along with their type and category\nfunc readTags() {\n\tconfiguration := instana.NewConfiguration()\n\tconfiguration.Host = \"tenant-unit.instana.io\"\n\tconfiguration.BasePath = \"https://tenant-unit.instana.io\"\n\n\tclient := instana.NewAPIClient(configuration)\n\tauth := context.WithValue(context.Background(), instana.ContextAPIKey, instana.APIKey{\n\t\tKey: apiKey,\n\t\tPrefix: \"apiToken\",\n\t})\n\n\ttags, _, err := client.ApplicationCatalogApi.GetApplicationTagCatalog(auth)\n\tif err != nil {\n\t\tfmt.Fatalf(\"Error calling the API, aborting.\")\n\t}\n\n\tfor _, tag := range tags {\n\t\tfmt.Printf(\"%s (%s): %s\\n\", tag.Category, tag.Type, tag.Name)\n\t}\n}\n```\n\n### Java\nDownload the latest openapi generator cli:\n```\nwget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.jar -O openapi-generator-cli.jar\n```\n\nA list for calls for different java http client implementations, which creates a valid generated source code for our spec.\n```\n//Nativ Java HTTP Client\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8 --library native\n\n//Spring WebClient\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library webclient\n\n//Spring RestTemplate\njava -jar openapi-generator-cli.jar generate -i https://instana.github.io/openapi/openapi.yaml -g java -o pkg/instana/openapi --skip-validate-spec -p dateLibrary=java8,hideGenerationTimestamp=true --library resttemplate\n\n```\n"
},
"servers": [
{
"description": "Instana Backend",
"url": "https://{unit}-{tenant}.instana.io",
"variables": {
"tenant": {
"default": "tenant",
"description": "Customer tenant unit"
},
"unit": {
"default": "unit",
"description": "Customer tenant name"
}
}
}
],
"tags": [
{
"name": "Infrastructure Analyze",
"description": "This endpoint group exposes the functions that are used by the Instana **Analyze Infrastructure** dashboards.\nTwo of the endpoints provide a [list of entity types](#operation/getAvailablePlugins) and [metrics for an entity type](#operation/getAvailableMetrics).\nIt is also possible to [search and filter entities](#operation/getEntities) and [aggregate metrics on similar entities](#operation/getEntityGroups).\n\n## Important notes\n\n### Prerequisites\n\nFor self-hosted installations, BeeInstana is required for this endpoint group.\nSee this [documentation for enabling BeeInstana](https://www.ibm.com/docs/en/instana-observability/current?topic=premises-installing-instana-backend-docker#beeinstana-metric-pipeline-beta).\n\n### Timeframe\n\n**timeFrame** As in the Instana dashboards, you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with specified granularity, a default granularity will be used for adjustment.\n\n### Metrics\n\n**metric** refers to the metric name. Query the [list of available metrics](#operation/getAvailableMetrics) for existing metrics on an entity type.\nThis is to be used when requesting metrics or when ordering by a metric. For **order.by**, `label` may also be used.\n\n### Filtering\n\nAs in the Instana dashboards, you can **filter by a tag**. Query the [infrastructure tag catalog](#operation/getInfrastructureCatalogMetrics) to retrieve a list of available tags."
},
{
"name": "Infrastructure Metrics",
"description": "This endpoint retrieves the metrics for infrastructure components.\r\n\r\n### Mandatory Parameters\r\n**plugin:** Plugins are entities' for which we collect metrics, for example : \"Host\", \"Cassandra node\", \"Cassandra Connection\".\r\n\r\nThe available plugins are depending on the system you are monitoring. Therefore you will need to [retrieve plugins](#operation/getInfrastructureCatalogPlugins) where we have data for you.\r\n\r\n**query or snapshotIds:** choose between dynamic focus query or [snapshotId](#operation/getSnapshots) (a unique identifier the metrics are assigned to)\r\n\r\nTo make the it easy to get started this endpoint has two modes that can be used for metrics retrieval:\r\n1. Search metrics with a query\r\n You are using the [Dynamic Focus](https://docs.instana.io/core_concepts/dynamic_focus/) query to filter the result.\r\n To get usable search parameters you can either query the search [catalog endpoint](#operation/getInfrastructureCatalogSearchFields) or use the UI\r\n\r\n1. Search for metrics for snapshotIds\r\n For advanced use cases, pagination for example, its recommended to use fixed snapshotIds.\r\n\r\n**metrics:** Id of the exact metric you want to retrieve, eg. \"cpu.user\", \"clientrequests.read.mean\"\r\n\r\nOnce you have selected the plugin you can define up to five metrics you want to retrieve with the call.\r\nPlease use our [metrics catalog call](#operation/getInfrastructureCatalogMetrics) to get the available metrics for the selected plugin.\r\n\r\n### Optional Parameters\r\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\r\n```\r\n windowSize to\r\n (ms) (unix-timestamp)\r\n<----------------------|\r\n```\r\n\r\n**rollup:** Depending on the selected timeFrame its possible to selected the rollup.\r\n\r\nThe available rollup is depending on two factors:\r\n1. [Retention times](https://docs.instana.io/core_concepts/data_collection/#data-retention)\r\n\r\n\tFor example if you select a to timestamp that is 3 Weeks in the past the most accurate rollup you can query for would be 1min\r\n1. Size of the selected windowSize\r\n\r\n\tThe limitation is that we only return 600 Data points per call, thus if you select a windowSize of 1hour the most accurate rollup you can query for would be 5s\r\n\r\nValid rollups are:\r\n\r\n| rollup | value |\r\n| ------------- | ------------- |\r\n| 1 second | 1 |\r\n| 5 seconds | 5 |\r\n| 1 minute | 60 |\r\n| 5 minutes | 300 |\r\n| 1 hour | 3600 |\r\n\r\n\r\n### Defaults\r\n**timeframe:**\r\n```\r\n\"timeFrame\": {\r\n\t\"windowSize\": 60000,\r\n\t\"to\": {current timestamp}\r\n}\r\n```\r\n\r\n**rollup**: 1\r\n\r\n### Limits\r\n1000 Calls per Hour\r\n\r\nTo keep the response size reasonable the limit is set to 30 retrieved items. To implement pagination see [1]\r\n\r\nA maximum of 600 data points are returned per metric.\r\n\r\nYou can only retrieve metrics [above](https://docs.instana.io/core_concepts/dynamic_graph/) the selected Dynamic Focus filter. Work around can be found under [2]\r\n\r\nThe following example will return an empty result, because the selected plugin \"host\" is below the dynamic focus filter \"java\" :\r\n```\r\nquery=entity.selfType:java\r\nplugin=host\r\nmetric=cpu.steal\r\n```\r\n### Tips\r\n[1] **Pagination**\r\nSometimes the query you are interested in returns more than 30 items, you have to use the [find snapshots](#operation/getSnapshots) endpoint to get a full list of Ids for your query and then use the [metrics endpoint](#operation/getInfrastructureMetrics) with the returned snapshotIds\r\n\r\n\r\n[2] **Application filter**\r\nYou can work around the aforementioned limitation by querying one of the crosscutting entities like applications, services and endpoints. For the example above you could create an Application with jvm.version isPresent filter. And search Query then for the created application name\r\n```\r\nquery=entity.application.name:\"Java Applications\"\r\n```\r\n"
},
{
"name": "Infrastructure Resources"
},
{
"name": "Infrastructure Catalog",
"description": "The endpoints of this group retrieve all available resources to query infrastructure metrics.\n"
},
{
"name": "Infrastructure Topology"
},
{
"name": "Application Metrics",
"description": "The endpoints of this group retrieve the metrics for defined applications, discovered services and endpoints.\r\n### Mandatory Parameters\r\n\r\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\r\n1. *metric* select a particular metric to get a list of available metrics query the [catalog endpoint](#operation/getApplicationCatalogMetrics)\r\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getApplicationCatalogMetrics) gives you the metrics with the available aggregations.\r\n\r\n### Optional Parameters\r\n\r\n**metrics** Default you will get an aggregated metric with for the selected timeframe \r\n\r\n* *granularity* \r\n * If it is not set you will get a an aggregated value for the selected timeframe\r\n * If the granularity is set you will get data points with the specified granularity **in seconds**\r\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\r\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\r\n \r\n**pagination** if you use pagination you most probably want to fix the timeFrame for the retrieved metrics\r\n1. *page* select the page number you want to retrieve\r\n2. *pageSize* set the number of applications you want to return with one query\r\n\r\n**order** You can order the returned items alphanumerical by label, either ascending or descending\r\n1. *by* if the granularity is set to 1 you can use the metric name eg. \"latency.p95\" to order by that value\r\n1. *direction* either ascending or descending\r\n\r\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\r\n```\r\n windowSize to\r\n (ms) (unix-timestamp)\r\n<----------------------|\r\n```\r\n\r\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with granularity, a default granularity will be used for adjustment.\r\n\r\nTo narrow down the result set you have four options to search for an application.\r\n\r\n**nameFilter | applicationId | serviceId | endpointId**\r\n\r\n* *nameFilter:* filter by name with \"contains\" semantic.\r\n\r\n* *applicationId:* search directly for an application by applicationId \r\n\r\n* *serviceId:* search for applications that include a particular service by serviceId\r\n\r\n* *endpointId:* search for applications that include a particular endpoint by endpointId\r\n\r\n### Defaults\r\n\r\n**metrics**\r\n* *granularity:* 1\r\n\r\n**order**\r\n* by application label ascending.\r\n\r\n**timeFrame**\r\n```\r\n\"timeFrame\": {\r\n\t\"windowSize\": 60000,\r\n\t\"to\": {current timestamp}\r\n}\r\n```\r\n**nameFilter | applicationId | serviceId | endpointId**\r\n* no filters are applied in the default call\r\n"
},
{
"name": "Application Catalog",
"description": "The endpoints of this group retrieve all available resources to query application metrics.\n"
},
{
"name": "Application Resources"
},
{
"name": "Application Analyze",
"description": "The following four endpoints expose our analyze functionality.\nPart of this are two group endpoints to retrieve metrics for traces and calls rolled up and filtered individually. \nFurthermore you can [search and filter all traces](#operation/getTraces) and retrieve [all details](#operation/getTrace) attached to the trace.\n\n## Parameters\n### Mandatory Parameters (only for group Endpoints):\n**group** It is mandatory to select a tag by which the calls and traces are grouped for the distinct endpoint call\n* *groupByTag* select a tag by which the calls and traces are grouped \n * a full list of available tags can be retrieved from the [application tag catalog](#operation/getApplicationTagCatalog)\n * for the trace endpoint only two tags are reasonable and working: `trace.endpoint.name` and `trace.service.name` which indicate the entry endpoint or service for the trace\n* *groupByTagSecondLevelKey* tags of type KEY_VALUE_PAIR need a second parameter e.g for `kubernetes.deployment.label` you would need provide the label you want to groupBy here.\n\n### Optional Parameters\n**pagination**\n* *offset* set the starting point for the data retrieval\n* *retrievalSize* you set the number of returned values\n* *ingestionTime* if you want to paginate through your result set you are interested in having the data for a fixed time point, the results set has a `cursor` class that has a ingestionTime property that indicates what you have to enter here.\n**order**\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with granularity, a default granularity will be used for adjustment.\n\n**tagFilters** As in the UI you able to filter your query by a tag. To get a list of all available tags you can query the [application tag catalog](#operation/getApplicationTagCatalog)\n* *name* The name of the tag as returned by the catalog\n* *value* The filter value of the tag, possible types are:\n * \"STRING\" alphanumerical values, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n * \"NUMBER\" numerical values, valid operators: \"EQUALS\", \"LESS_THAN\" \"GREATER_THAN\"\n * \"KEY_VALUE_PAIR\" \n* *operator* one of the valid operators for the type of the selected tag\n\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\n1. *metric* select a particular metric, available metrics in this context are\n * Latency Mean\n * Error Rate\n * Traces Sum\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getApplicationCatalogMetrics) gives you the metrics with the available aggregations.\n3. *granularity* \n * If it is not set you will get a an aggregated value for the selected timeframe\n * If the granularity is set you will get data points with the specified granularity **in seconds**\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\n\n### Defaults:\n**timeFrame**\n```\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n"
},
{
"name": "Application Settings"
},
{
"name": "Application Topology"
},
{
"name": "Website Metrics"
},
{
"name": "Website Catalog",
"description": "The endpoints of this group retrieve all available resources to query website metrics.\n"
},
{
"name": "Website Configuration"
},
{
"name": "Website Analyze",
"description": "The following four endpoints expose our analyze functionality.\n\n## Mandatory Parameters :\n\n**type** \n\n**group (only for group Endpoints)** It is mandatory to select a tag by which the beacons are grouped for the distinct endpoint call\n* *groupByTag* select a tag by which the beacons are grouped \n * a full list of available tags can be retrieved from the [website tag catalog](#operation/getWebsiteCatalogTags)\n* *groupByTagSecondLevelKey* tags of type KEY_VALUE_PAIR need a second parameter e.g for `beacon.meta` you would need provide the label you want to groupBy here.\n\n\n## Optional Parameters:\n\n**pagination**\n* *offset* set the starting point for the data retrieval\n* *retrievalSize* you set the number of returned values\n* *ingestionTime* if you want to paginate through your result set you are interested in having the data for a fixed time point, the results set has a `cursor` class that has a ingestionTime property that indicates what you have to enter here.\n\n**order**\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\n\n**tagFilterExpression** As in the UI you are able to filter your query using tags and operators such as `AND` and `OR`. To get a list of all available tags you can query the [tag catalog](#operation/getWebsiteCatalogTags)\n* *name* The name of the tag as returned by the catalog, e.g `beacon.meta`, `beacon.http.path`\n* *value* The filter value of the tag, possible types are:\n * \"STRING\" alphanumerical values, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n * \"NUMBER\" numerical values, valid operators: \"EQUALS\", \"LESS_THAN\" \"GREATER_THAN\"\n * \"KEY_VALUE_PAIR\" of you are using meta tags `beacon.meta` you can filter for those by setting `yourMetaTagName=foo` in the value field, valid operators: \"EQUALS\", \"CONTAINS\", \"NOT_EQUAL\", \"NOT_CONTAIN\", \"NOT_EMPTY\", \"IS_EMPTY\"\n* *operator* one of the valid operators for the type of the selected tag\n\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\n1. *metric* select a particular metric, available metrics in this context are\n * Latency Mean\n * Error Rate\n2. *aggregation* depending on the selected metric different aggregations are available e.g. SUM, MEAN, P95. The aforementioned [catalog endpoint](#operation/getWebsiteCatalogMetrics) gives you the metrics with the available aggregations.\n3. *granularity* \n * If it is not set you will get a an aggregated value for the selected timeframe\n * If the granularity is set you will get data points with the specified granularity **in seconds**\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\n \n\n## Defaults:\n\n**timeFrame**\n```\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n"
},
{
"name": "Mobile App Metrics"
},
{
"name": "Mobile App Catalog"
},
{
"name": "Mobile App Configuration"
},
{
"name": "Mobile App Analyze"
},
{
"name": "Events"
},
{
"name": "Event Settings"
},
{
"name": "Application Alert Configuration",
"description": "The API endpoints of this group can be used to manage Application alert configurations.\n\n## Parameters:\n\n- **id:** ID of the application alert config which needs to be updated.\n\n- **name:** Name for the application alert configuration.\n\n- **description:** Description for the application alert configuration.\n\n- **severity:** The severity of the alert when triggered, which is either `5` (Warning), or `10` (Critical).\n\n- **triggering:** Optional flag to indicate whether also an Incident is triggered or not.\n\n- **applications:** Selection of application, services and endpoints in scope.\n\n The selection defines a tree of included or excluded sub entities. The defined `inclusive` flag defines whether this node and his child nodes are included (`inclusive: true`) or excluded (`inclusive: false`) by default. Empty selections or unnecessary selections are not allowed. \n\n #### Example 1: Select an entire Application Perspective\n\n To select the entire application with ID `<appId>` including all its services and endpoints, simply provide the following selection object:\n\n ```json\n \"applications\": {\n \"<appId>\": {\n \"applicationId\": \"<appId>\"\n }\n }\n ```\n\n Leaf nodes of the selection tree default to `true` if no `inclusive` value is defined.\n\n #### Example 2: Specific selection of services and endpoints\n\n To select not the entire application with ID `<appId>`, but only the entire serivces Service1 with ID `<service1>` and Service2 with ID `<service2>`, with the exception of endpoint `<endpoint2>` of Service2. And in addition, only Endpoint `<endpoint3>` of Service3 with id `<service3>`, then use the following selection:\n\n ```json\n \"applications\": {\n \"<appId>\": {\n \"applicationId\": \"<appId>\",\n \"inclusive\": false,\n \"services\": {\n \"<service1>\": {\n \"serviceId\": \"<service1>\"\n },\n \"<service2>\": {\n \"serviceId\": \"<service2>\",\n \"inclusive\": true,\n \"endpoints\": {\n \"<endpoint2>\": {\n \"endpointId\": \"<endpoint2>\",\n \"inclusive\": false\n }\n }\n },\n \"<service3>\": {\n \"serviceId\": \"<service3>\",\n \"inclusive\": false,\n \"endpoints\": {\n \"<endpoint3>\": {\n \"endpointId\": \"<endpoint3>\",\n \"inclusive\": true\n }\n }\n }\n }\n }\n }\n ``` \n\n- **boundaryScope:** Boundary scope of the Application Perspective\n\n- **tagFilterExpression:** Boolean expression of tag filters to define the scope of relevant calls.\n\n- **includeInternal:** Optional flag to indicate whether also internal calls are included in the scope or not. The default is `false`.\n\n- **includeSynthetic:** Optional flag to indicate whether also synthetic calls are included in the scope or not. The default is `false`.\n\n- **evaluationType:** The alert evaluation type of the alert configuration. For example, this allows to configure whether calls of the configured scope is aggregated to a single metric that is then considered for alerting (`\"PER_AP\"`), or whether each service of an Appliction Perspective is is evaluated individually (`\"PER_AP_SERVICE\"`).\n\n- **granularity:** The evaluation granularity used for detection of violations of the defined threshold. In other words, it defines the size of the tumbling window used.\n\n- **rule:** Indicates the type of rule this alert configuration is about.\n\n- **threshold:** Indicates the type of threshold this alert rule is evaluated on .\n\n- **timeThreshold:** Indicates the type of violation of the defined threshold.\n\n- **alertChannelIds:** List of IDs of alert channels defined in Instana.\n\n## Deprecated Parameters\n\n- **applicationId:** Unique ID of the Application Perspective. It is replaced by **applications**."
},
{
"name": "Global Application Alert Configuration",
"description": "The API endpoints of this group can be used to manage Global Application alert configurations.\n\n## Parameters:\n\nAll parameters and deprecated parameters are similar to Application Alert Configuration except **applications**\n\n- **applications:** Selection of applications, services and endpoints in scope. It allows more than one application to define a global rule across different Application Perspectives.\n\n #### Example: Select multiple Application Perspectives\n\n To select multiple applications with IDs `<appId1>`, `<appId2>` including all its services and endpoints, simply provide the following selection object:\n\n ```json\n \"applications\": {\n \"<appId1>\": {\n \"applicationId\": \"<appId1>\"\n },\n \"<appId2>\": {\n \"applicationId\": \"<appId2>\"\n }\n }\n ```\n"
},
{
"name": "Infrastructure Alert Configuration"
},
{
"name": "Synthetic Alert Configuration",
"description": "The API endpoints of this group can be used to manage alert configurations for Synthetic Monitoring.\n\n## Parameters:\n\n- **id:** ID of the alert configuration.\n\n- **name:** Name for the synthetic alert configuration, which is used as the title of the event when triggered.\n\n- **description:** Description for the synthetic alert configuration, which is used as the detials of the triggerd event.\n\n- **severity:** The severity of the alert when triggered, which is either `5` (Warning), or `10` (Critical).\n\n- **syntheticTestIds:** List of synthetic test IDs this alert configuration is applied to. Check out APIs in [Synthetic Monitoring](#tag/Synthetic-Settings) to e.g. get a [list of all synthetic tests](#operation/getSyntheticTests) available.\n\n- **rule:** Indicates the type of rule this alert configuration is about. The only `alertType` available so far is `\"failure\"`, where the metric name `\"status\"` is expected. This boolean metric requires no threshold to be specified, because value of `status=0` indicates a test failure.\n\n- **timeThreshold:** Defines the triggering condition in time, such as how many consecutive test failures are required to open an event. Setting a higher value for `violationsCount` helps to reduce the number of alerts.\n\n- **alertChannelIds:** List of IDs of alert channels defined in Instana.\n\n"
},
{
"name": "Host Agent",
"description": "Endpoints of this group can be used to list and configure host agents. "
},
{
"name": "User"
},
{
"name": "Groups",
"description": "Groups are used to permit individual users to perform specific actions and get visibility to an access scope. Each user can be assigned to multiple groups, every one coming with its associated permissions. In addition a group sets the access scope and you can configure the visible areas for the group members.\n\nWhen you are a member of multiple groups, your permissions have an additive effect.\n\nGranting access to certain entities within Instana (e.g. Applications, Kubernetes Clusters etc.) is done through a corresponding entry in the `permissionSet` payload.\n"
},
{
"name": "Audit Log"
},
{
"name": "API Token"
},
{
"name": "Session Settings"
},
{
"name": "Maintenance Configuration",
"description": "### Maintenance Windows\nMaintenance windows allow you to mute alerts.\n\n### Types of Maintenance Configurations\n**One-Time**: Executed once at a fixed scheduled time, after which the configuration expires.\n\n**Recurrent**: Executed on a schedule basis (e.g., daily, weekly, monthly, or yearly).\n\n### Pausing or Resuming Maintenance Configurations\nMaintenance windows can be paused or resumed.\n\nIf a maintenance configuration is paused, alerts for the events matching the scope of the configuration will no longer be muted. \n"
},
{
"name": "Synthetic Calls"
},
{
"name": "Releases"
},
{
"name": "SLI Settings",
"description": "## Deprecated Parameters\n**tagFilters** The list of tag filters. It is replaced by **tagFilterExpression**"
},
{
"name": "SLI Report"
},
{
"name": "Health"
},
{
"name": "Custom Dashboards",
"description": "You can use these API endpoints to manage custom dashboards. We recommend\nthat you leverage the `Edit as JSON` feature found within our user interface\nto construct the desired request payloads. Specifically to help you build\ncorrect widget configurations and access rules.\n\nTo identify the correct values for the `relatedId` field of the access rules,\nwe recommend using the `/api/custom-dashboard/shareable-users` and\n`/api/custom-dashboard/shareable-api-tokens` endpoints. These endpoints return\nour internal IDs for users and API tokens."
},
{
"name": "Usage"
},
{
"name": "Synthetic Catalog"
},
{
"name": "Synthetic Settings",
"description": "The API endpoints of this group can be used to manage Synthetic Locations, Synthetic Tests and Synthetic Credentials. \n\n## Synthetic Location Properties:\n- **id** Unique identifier of the location resource.\n- **label** Friendly name of the location.\n- **description** The description of the location.\n- **locationType** Indicates if the location is public or private.\n- **playbackCapability** The playback capabilities provided by this location resource.\n The playbackCapability object has the following properties: \n - **syntheticType** Different types of synthetic tests that can be executed at this location. \n Possible values are HTTPAction, HTTPScript, BrowserScript (Beta), WebpageAction (Beta), and WebpageScript (Beta). \n The values are corresponding to the syntheticType parameter available in the createSyntheticTest endpoint.\n - **browserType** Different types of supported Web browsers when creating synthetic tests for BrowserScript, WebpageAction and WebpageScript.\n Right now, only Chrome and Firefox are supported. \n- **geoPoint** An object includes the longitude, latitude, country name, and city name properties of a location. \n- **popVersion** PoP's version\n- **customProperties** An object with name/value pairs to provide additional information of the Synthetic location.\n- **createdAt** The location created time, following RFC3339 standard.\n- **modifiedAt** The location modified time, following RFC3339 standard.\n- **observedAt** The timestamp when PoP requests a Synthetic test, following RFC3339 standard.\n\n## Synthetic Test Properties:\n- **id** Unique identifier of the Synthetic test resource.\n- **label** Friendly name of the Synthetic test resource.\n- **description** The description of the Synthetic test.\n- **active** Indicates if the Synthetic test is started or not. The default is true.\n- **applicationId** Unique identifier of the Application Perspective.\n- **configuration** An object which has two properties: syntheticType and the corresponding configuration object:\n - **syntheticType** The type of the Synthetic test. Supported values are HTTPAction, HTTScript, BrowserScript (Beta), WebpageAction (Beta),\n and WebpageScript (Beta). The locations assigned to execute this Synthetic\n test must support this syntheticType, i.e. the location's playbackCapabilities property.\n - **markSyntheticCall** Flag used to control if HTTP calls will be marked as synthetic calls/endpoints in Instana backend, so they can be ignored when calculating service and application KPIs, users can also check \"Hide Synthetic Calls\" checkbox to hide/show them in UI.\n - **retries** An integer type from 0 to 2, 0 by default.\n It indicates how many attempts (max 2) will be allowed\n to get a successful connection (not necessarily a successful result).\n Failures like socket hangups, gateway timeouts, and DNS lookup fails cause retires, but 404's 400's, do not.\n - **retryInterval** The time interval between retries in seconds. The default is 1s, max is 10s.\n - **timeout** The timeout to be used by the PoP playback engines running the test. Values are in integers followed by a time unit (ms, s, m). \n It is the minimum value of test configuration `timeout`, `testFrequency` and `maxTimeout` configured in PoP deployment.\n - If user defined timeout value exceeds the `maxTimeout` or `testFrequency` in test configuration, the timeout value does not take effect \n and PoP playback engines use the smaller one of `maxTimeout` and `testFrequency` as the actual timeout value.\n - If timeout value in test configuration is not provided, the default value is **1m** for HTTPAction and HTTPScript tests. \n BrowserScript, WebpageAction, and WebpageScript tests use the smaller one of `maxTimeout` and `testFrequency` as the actual timeout value.\n - **XXXConfiguration** The configuration corresponding to the syntheticType. Configuration types are HTTPActionConfiguration, HTTPScriptConfiguration,\n BrowserScriptConfiguration (Beta), WebpageActionConfiguration (Beta), and WebpageScriptConfiguration (Beta). \n - **HTTPActionConfiguration** has the following properties:\n - **url** The URL is being tested. It is required.\n - **syntheticType** Its value is HTTPAction. It is required.\n - **operation** An operation being used must be one of GET, HEAD, OPTIONS, PATCH, POST, PUT, and DELETE. By default, it is GET.\n - **headers** An object with header/value pairs\n - **header** The header to be sent in operation. It should not contain the terminating ':' character.\n - **value** The value of the header.\n - **body** The body content to send with the operation.\n - **validationString** An expression to be evaluated.\n - **followRedirect** A boolean type, true by default; to allow redirect.\n - **allowInsecure** A boolean type, true by default; if set to true then allow insecure certificates\n (expired, self-signed, etc).\n - **expectStatus** An integer type, by default, the Synthetic passes for any 2XX status code.\n This forces just one status code to cause a pass, including what would normally be a fail, for example, a 404.\n - **expectJson** An optional object to be used to check against the test response object.\n - **expectMatch** An optional regular expression string to be used to check the test response.\n - **expectExists** An optional list of property labels used to check if they are present in the test response object.\n - **expectNotEmpty** An optional list of property labels used to check if they are present in the test response object with a non-empty value.\n - **HTTPScriptConfiguration** has the following properties:\n - **script** The Javascript content, it is plain text, not base64 encoded. **script** and **scripts** are mutually exclusive.\n - **scripts** Multi script package. **script** and **scripts** are mutually exclusive.\n - **scriptFile** The name of the file to run\n - **bundle** All required js files bundled up into a single zip file with base64 encoded\n - **syntheticType** Its value is HTTPScript. It is required.\n - The API Script Guide, including examples, can be found at: https://www.ibm.com/docs/en/instana-observability/current?topic=monitoring-using-api-scripts\n - **BrowserScriptConfiguration** has the following properties:\n - **script** A Node.js based test script, it is plain text, not base64 encoded. **script** and **scripts** are mutually exclusive.\n - **scripts** Multi script package. **script** and **scripts** are mutually exclusive.\n - **scriptFile** The name of the file to run\n - **bundle** All required js files bundled up into a single zip file with base64 encoded\n - **scriptType** The type of the script, right now, only Basic type is supported. \n - **browser** The type of the browser: chrome or firefox, chrome by default.\n - **recordVideo** A boolean type, false by default.\n - **syntheticType** Its value is BrowserScript. It is required.\n - **WebpageActionConfiguration** has the following properties:\n - **url** The URL of the Web page being tested. It is required.\n - **browser** The type of the browser: chrome or firefox, chrome by default.\n - **recordVideo** A boolean type, false by default.\n - **syntheticType** Its value is WebpageAction. It is required.\n - **WebpageScriptConfiguration** has the following properties:\n - **script** A Selenium IDE recording script. It is required.\n - **browser** The type of the browser: chrome or firefox, chrome by default.\n - **recordVideo** A boolean type, false by default.\n - **syntheticType** Its value is WebpageScript. It is required.\n- **createdAt** The test created time, following RFC3339 standard.\n- **createdBy** The user identifier who created the test resource.\n- **customProperties** An object with name/value pairs to provide additional information of the Synthetic test.\n- **locations** It is an array of the PoP location IDs where the Synthetic tests are located.\n- **modifiedAt** The test last updated time, following RFC3339 standard.\n- **modifiedBy** The user identifier who updated the test resource.\n- **playbackMode** Defines how the Synthetic test should be executed across multiple\n PoPs. This property is optional, and its default value is Simultaneous, and only Simultaneous is supported, i.e.,\n Synthetic tests run at all locations simultaneously. \n- **testFrequency** How often the playback for a Synthetic test is scheduled. The unit of the testFrequency parameter is minute.\n The default is every 15 minutes. The range is from 1 minute to 120 minutes.\n\n## Synthetic Credentials:\n\nSynthetic credentials can be used to store passwords and/or secrets used by the Synthetic Tests.\n\nAll Script Tests can use credentials in their body and API Simple Tests can use them on header parameters.\n\nIt is required that the credentials used in the test be created before the test is created or modified.\n\nTests using credentials are validated during test creation and update whether you use the API or UI, as follows:\n\n1. The user Id of the logged in user or API Token being used to create or modify the test must have permission to use credentials. \n Requests to create or update a test referencing credentials without the correct permission will fail with return code `Forbidden`.\n\n2. The credentials or secrets used in the test must exist. \n Requests to create or update a test referencing credentials that do not exist will fail with return code `Bad Request`."
},
{
"name": "Synthetic Test Playback Results",
"description": "The endpoints of this group retrieve the results for defined Synthetic tests.\n\n**Note on names in TagFilter/TagFilterExpression**: From R243, the name used in a TagFilter or a TagFilterExpression has the format: synthetic.\\<name\\>.\nIt can be one of the following: synthetic.id (id is the test result id), synthetic.testId,\nsynthetic.testName, synthetic.locationId, synthetic.applicationId, synthetic.serviceId, synthetic.syntheticType,\nsynthetic.locationName, and synthetic.locationLabel. If it is a metric name, then the format is: synthetic.metrics\\<MetricName\\>.\nFor example, synthetic.metricsResponseTime, synthetic.metricsStatus.\n\nThe names used prior to R243 should be considered as deprecated. They will be accepted temporarily and will be removed in an upcoming release.\n\n## Get Synthetic test playback results \nThe endpoint returns the aggregated Synthetic test result data\n\n### Mandatory Parameters \n\n**testId** An array of the unique identifiers of Synthetic tests\n\n**metrics** A list of metric objects that define which metric should be returned, with the defined aggregation. Each metrics objects consists of minimum two items:\n1. *metric* select a particular metric. This is the list of available metrics for all types of Synthetic Tests: \n synthetic.metricsResponseTime (ms), synthetic.metricsResponseSize (bytes), synthetic.metricsStatusCode (an integer represents an HTTP response code, e.g., 200, 401, 500), synthetic.metricsRequestSize (bytes), \n synthetic.metricsUploadSpeed (bytes per second), synthetic.metricsDownloadSpeed (bytes per second), \n synthetic.metricsRedirectTime (ms), synthetic.metricsRedirectCount, synthetic.metricsConnectCount, synthetic.metricsStatus (an integer, 1-success or 0-failure), and synthetic.tags (list of custom properties and values). \n \n The following metrics are only available for the HTTPAction type Synthetic Tests: synthetic.metricsBlocking (bytes), synthetic.metricsDns (bytes), synthetic.metricsConnect (bytes), synthetic.metricsSsl (bytes), \n synthetic.metricsSending (bytes), synthetic.metricsWaiting (bytes), and synthetic.metricsReceiving (bytes).\n\n The metric synthetic.tags adds the latest list of custom properties to the response.\n\n2. *aggregation* Depending on the selected metric, different aggregations are available e.g., SUM, MEAN, P90 (90th percentile), DISTINCT_COUNT, and MAX. MAX is only allowed for synthetic.tags.\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\nThe timeFrame might be adjusted to fit the metric granularity so that there is no partial bucket. For example, if the query timeFrame is 08:02 - 09:02 and the metric granularity is 5 minutes, the timeFrame will be adjusted to 08:05 - 09:00. The adjusted timeFrame will be returned in the response payload. If the query does not have any metric with granularity, a default granularity will be used for adjustment.\n\n### Optional Parameters\n\n**metrics** By default you will get an aggregated metric for the selected timeframe\n\n* *granularity*\n * If it is not set you will get an aggregated value for the selected timeframe\n * If the granularity is set you will get data points with the specified granularity **in seconds**\n * The granularity should not be greater than the `windowSize` (important: `windowSize` is expressed in **milliseconds**)\n * The granularity should not be set too small relative to the `windowSize` to avoid creating an excessively large number of data points (max 600)\n * The granularity values are the same for all metrics\n\n**pagination** if you use pagination you most probably want to fix the timeFrame for the retrieved metrics\n1. *page* select the page number you want to retrieve\n2. *pageSize* set the number of Synthetic test results you want to return with one query\n\n**order** You can order the returned items alphanumerical by label, either ascending or descending\n1. *by* Use the metric name, e.g. \"synthetic.metricsResponseTime\", to order by its value\n2. *direction* either ascending (ASC) or descending (DESC)\n\n**tagFilters** It serves as a filter to narrow down return results.\nIt will be replaced by **tagFilterExpression**.\n\n**tagFilterExpression** It serves as a filter to narrow down return results. Its type can be either EXPRESSION or TAG_FILTER with\nlogical operators AND or OR.\n\nA payload only needs either tagFilters or tagFilterExpression as a filter, not both.\n\nEither tagFilters or tagFilterExpression can specify a custom property by its key and value.\n```\n\"tagFilters\":[{\n \"name\":\"synthetic.tags\",\n \"key\":\"location\",\n \"value\":\"Denver\",\n \"operator\":\"EQUALS\"\n}]\n```\n\nTo narrow down the result set you have two options to search for a test.\n\n**locationId | applicationId**\n\n* *synthetic.locationId:* filter by locationId\n\n* *synthetic.applicationId:* filter by applicationId\n\n### Defaults\n\n**metrics**\n* *granularity:* 0\n\n**timeFrame**\n```\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n**locationId | applicationId**\n* no filters are applied in the default call\n\n### Sample payload to get a Synthetic test result\n```\n{\n \"testId\": [\"tUmWgvzdo1Q1vpVRpzR5\", \"Pg0Q1UqHRd7OMysohVLd\"],\n \"//comment1\": \"Get test results from last 30 minutes (windowSize), data are aggregated every 10 minutes (granularity)\",\n \"//comment2\": \"The granularity values for responseTime and responseSize must be the same\"\n \"metrics\": [\n {\n \"aggregation\": \"MEAN\",\n \"granularity\": 600, \n \"metric\": \"synthetic.metricsResponseTime\"\n },\n {\n \"aggregation\": \"MEAN\",\n \"granularity\": 600, \n \"metric\": \"synthetic.metricsResponseSize\"\n }],\n \"timeFrame\": {\n \"to\": 0,\n \"windowSize\": 1800000 \n }\n}\n```\n\n## Get a list of Synthetic test playback results (no aggregation)\n### Mandatory Parameters\n**syntheticMetrics** It is an array of metrics. The available metrics for all types of Synthetic Tests: synthetic.id (a string representing the test result ID), \nsynthetic.metricsResponseTime (ms), synthetic.metricsResponseSize (bytes), synthetic.metricsStatusCode (an integer represents an HTTP response code, e.g., 200, 401, 500), synthetic.metricsRequestSize (bytes),\nsynthetic.metricsUploadSpeed (bytes per second), synthetic.metricsDownloadSpeed (bytes per second),\nsynthetic.metricsRedirectTime (ms), synthetic.metricsRedirectCount, synthetic.metricsConnectCount, synthetic.metricsStatus (an integer, 1-success or 0-failure), and synthetic.tags (list of custom properties and values).\n\nThe following metrics are only available for the HTTPAction type Synthetic Tests: synthetic.metricsBlocking (bytes), synthetic.metricsDns (bytes), synthetic.metricsConnect (bytes), synthetic.metricsSsl (bytes),\nsynthetic.metricsSending (bytes), synthetic.metricsWaiting (bytes), and synthetic.metricsReceiving (bytes).\n\nThe metric synthetic.tags adds the latest list of custom properties to the response.\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n```\n\n### Optional Parameters\n**pagination** if you use pagination you most probably want to fix the timeFrame for the retrieved metrics\n1. *page* select the page number you want to retrieve\n2. *pageSize* set the number of Synthetic test results you want to return with one query\n\n**order** You can order the returned items alphanumerical by label, either ascending or descending\n1. *by* Use the metric name, e.g. \"synthetic.metricsResponseTime\" to order by that value\n2. *direction* either ascending (ASC) or descending (DESC)\n\n**tagFilters** It serves as a filter to narrow down return results. \nIt will be replaced by **tagFilterExpression**.\n\n**tagFilterExpression** It serves as a filter to narrow down return results. Its type can be either EXPRESSION or TAG_FILTER with \nlogical operators AND or OR.\n\nA payload only needs either tagFilters or tagFilterExpression as a filter, not both.\n\nEither tagFilters or tagFilterExpression can specify a custom property by its key and value.\n```\n\"tagFilters\":[{\n \"name\":\"synthetic.tags\",\n \"key\":\"location\",\n \"value\":\"Denver\",\n \"operator\":\"EQUALS\"\n}]\n```\n\n### Sample payload to get a list of Synthetic test results with tagFilters\n```json\n{\n \"syntheticMetrics\":[\"synthetic.metricsResponseTime\",\"synthetic.metricsResponseSize\"],\n \"order\":{\n \"by\":\"synthetic.metricsResponseTime\",\n \"direction\":\"DESC\"\n },\n \"tagFilters\":[{\n \"stringValue\":\"hYziqsaXSJmQsehOWg1S\",\n \"name\":\"synthetic.testId\",\n \"operator\":\"EQUALS\"\n }],\n \"timeFrame\": {\n \"to\": 0,\n \"windowSize\": 1800000\n }\n}\n```\n\n### Sample payload to get a list of Synthetic test results with tagFilterExpression\n```json\n{\n \"syntheticMetrics\":[\"synthetic.metricsResponseTime\",\"synthetic.metricsResponseSize\"],\n \"order\":{\n \"by\":\"synthetic.metricsResponseTime\",\n \"direction\":\"DESC\"\n },\n \"tagFilterExpression\": { \n \"type\":\"EXPRESSION\",\n \"logicalOperator\":\"AND\",\n \"elements\":[{\n \"stringValue\":\"hYziqsaXSJmQsehOWg1S\",\n \"name\":\"synthetic.testId\",\n \"operator\":\"EQUALS\"\n }, {\n \"name\": \"synthetic.locationId\", \n \"operator\": \"EQUALS\", \n \"stringValue\": \"abcdefgXSJmQsehOWg1S\"\n }]\n },\n \"timeFrame\": {\n \"to\": 0,\n \"windowSize\": 1800000\n }\n}\n```\n\n## Get a list of Synthetic tests with Success Rate and Average Response Time data\nThe endpoint returns a list of Synthetic tests with Success Rate and Average Response Time result data\n\n### Mandatory Parameters\n\n**metrics**\n1. *metric* select a particular metric. Right now, only synthetic.metricsResponseTime (ms) is supported.\n2. *aggregation* MEAN\n3. *granularity* 60\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n\n### Optional Parameters\n\n**pagination** if you use pagination you most probably want to fix the timeFrame for the retrieved metrics\n1. *page* select the page number you want to retrieve\n2. *pageSize* set the number of Synthetic test results you want to return with one query\n\n**order** You can order the returned items alphanumerical by label, either ascending or descending\n1. *by* Use the metric name, \"synthetic.metricsResponseTime\", to order by its value\n2. *direction* either ascending (ASC) or descending (DESC)\n\n**tagFilters** It serves as a filter to narrow down return results. The name of a tagFilter is one of the following: \nsynthetic.syntheticType, synthetic.locationId, and synthetic.applicationId.\nIt will be replaced by **tagFilterExpression**.\n```\n\"tagFilters\":[{\n \"stringValue\":\"hYziqsaXSJmQsehOWg1S\",\n \"name\":\"synthetic.applicationId\",\n \"operator\":\"EQUALS\"\n}]\n```\n\n**tagFilterExpression** It serves as a filter to narrow down return results. Its type can be either EXPRESSION or TAG_FILTER with\nlogical operators AND or OR.\n```\n\"tagFilterExpression\": { \n \"type\":\"EXPRESSION\",\n \"logicalOperator\":\"AND\",\n \"elements\":[{\n \"name\": \"synthetic.metricsStatus\", \n \"operator\": \"EQUALS\", \n \"numberValue\": 1\n }, {\n \"name\": \"synthetic.locationId\", \n \"operator\": \"EQUALS\", \n \"stringValue\":\"WnjlKKbgzLDnyGra6PAs\"\n }]\n}\n```\n\nA payload only needs either tagFilters or tagFilterExpression as a filter, not both.\n\nEither tagFilters or tagFilterExpression can specify a custom property by its key and value.\n```\n\"tagFilters\":[{\n \"name\":\"synthetic.tags\",\n \"key\":\"location\",\n \"value\":\"Denver\",\n \"operator\":\"EQUALS\"\n}]\n```\n\nTo narrow down the result set you have three options to search for a test.\n\n**syntheticType | locationId | applicationId**\n\n* *synthetic.syntheticType:* filter by syntheticType, either HTTPAction or HTTPScript\n\n* *synthetic.locationId:* filter by locationId\n\n* *synthetic.applicationId:* filter by applicationId\n\n\nTests can also be filtered by their active state (`true`/`false`) using the custom property label `synthetic.testActive`.\n```\n\"tagFilters\": [{ \n \"name\":\"synthetic.testActive\", \n \"operator\":\"EQUALS\",\n \"booleanValue\": false \n}]\n```\n\n### Defaults\n\n**syntheticType | locationId | applicationId**\n* no filters are applied in the default call\n\n### Sample payload to get a list of active Synthetic tests with SuccessRate and Average Response Time results\n```\n{\n \"metrics\": [\n {\n \"aggregation\": \"MEAN\",\n \"granularity\": 60, \n \"metric\": \"synthetic.metricsResponseTime\"\n }],\n \"tagFilterExpression\": { \n \"type\":\"EXPRESSION\",\n \"logicalOperator\":\"AND\",\n \"elements\":[{\n \"name\": \"synthetic.locationId\", \n \"operator\": \"EQUALS\", \n \"stringValue\": \"abcdefgXSJmQsehOWg1S\"\n }, {\n \"name\": \"synthetic.testActive\",\n \"operator\": \"EQUALS\",\n \"booleanValue\": true\n }]\n },\n \"timeFrame\": {\n \"to\": 0,\n \"windowSize\": 3600000 \n }\n}\n```\n\n## Get a list of Synthetic locations with Last Test Run on (each location) data\nThe endpoint returns a list of Synthetic locations with Last Test Run on (each location) result data\n\n### Mandatory Parameters\n\n**timeFrame** As in our UI you can specify the timeframe for metrics retrieval.\n```\n windowSize to\n (ms) (unix-timestamp)\n<----------------------|\n\n\"timeFrame\": {\n\t\"windowSize\": 60000,\n\t\"to\": {current timestamp}\n}\n```\n\n### Optional Parameters\n\n**pagination** if you use pagination you should use the same timeFrame for all of the pages you want to query\n1. *page* select the page number you want to retrieve\n2. *pageSize* set the number of Synthetic locations you want to return with one query\n\n**order** You can order the returned items alphanumerically by label, either ascending or descending\n1. *by* Use the metric name, e.g., \"location_name\", to order by its value\n2. *direction* either ascending (ASC) or descending (DESC)\n\n The sorting can be done on the following metrics: location_name, location_label, status, type, total_tests,\n last_test_run, and namespace\n\n**tagFilters** It serves as a filter to narrow down return results. The name of a tagFilter is one of the following: \nsynthetic.locationName, synthetic.locationLabel, and synthetic.locationId.\nIt will be replaced by **tagFilterExpression**.\n```\n\"tagFilters\":[{\n \"stringValue\":\"hYziqsaXSJmQsehOWg1S\",\n \"name\":\"synthetic.locationId\",\n \"operator\":\"EQUALS\"\n}]\n```\n\n**tagFilterExpression** It serves as a filter to narrow down return results. Its type can be either EXPRESSION or TAG_FILTER with\nlogical operators AND or OR.\n```\n\"tagFilterExpression\": { \n \"type\":\"EXPRESSION\",\n \"logicalOperator\":\"OR\",\n \"elements\":[{\n \"name\": \"synthetic.locationId\", \n \"operator\": \"EQUALS\", \n \"stringValue\":\"WnjlKKbgzLDnyGra6PAs\"\n }]\n}\n```\n\nA payload only needs either tagFilters or tagFilterExpression as a filter, not both.\n\n### Sample payload to get a list of Synthetic locations with Last Test Run on (each location) data\n```\n{\n \"order\": {\n \t\"by\": \"status\", \n \t\"direction\": \"Desc\"\n },\n \"timeFrame\": {\n \"to\": 0,\n \"windowSize\": 3600000 \n }\n}\n```\n\n## Get Synthetic test playback result detail data\n\n### Query Parameters\n**type** The type of the detailed data. Its value is one of these types: SUBTRANSACTIONS, LOGS, and HAR.\n\n**name** The name of the file to be retrieved, if more than one file available for the same type. Used when the type equals to LOGS or IMAGES\n\n## Download a Synthetic test playback result detail data file\n\n### Query Parameter\n**type** The type of a single compressed file. Its value is one of these types: SUBTRANSACTIONS, LOGS, IMAGES, VIDEOS, and HAR."
},
{
"name": "Automation Settings"
},
{
"name": "Authentication"
}
],
"paths": {
"/api/apdex/report/{apdexId}": {
"get": {
"operationId": "getApdexReport",
"parameters": [
{
"in": "path",
"name": "apdexId",
"required": true,
"schema": {
"type": "string",
"example": null
}
},
{
"in": "query",
"name": "from",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
},
{
"in": "query",
"name": "to",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
}
],
"responses": {
"default": {
"content": {
"application/json": {
"schema": {
"type": "array",
"example": null,
"items": {
"$ref": "#/components/schemas/ApdexReport"
}
}
}
}
}
},
"security": [
{
"ApiKeyAuth": []
}
],
"summary": "Generate Apdex report",
"tags": [
"Apdex Report"
]
}
},
"/api/application-monitoring/analyze/backend-correlation": {
"get": {
"operationId": "getCorrelatedTraces",
"parameters": [
{
"in": "query",
"name": "correlationId",
"required": true,
"schema": {
"type": "string",
"example": null,
"maxLength": 128,
"minLength": 0
}
}
],
"responses": {
"default": {
"content": {
"application/json": {
"example": [
{
"traceId": "c606ccf3578135c6"
}
],
"schema": {
"type": "array",
"example": null,
"items": {
"$ref": "#/components/schemas/BackendTraceReference"
}
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Resolve backend trace IDs using correlation IDs from website and mobile app monitoring beacons.",
"tags": [
"Application Analyze"
]
}
},
"/api/application-monitoring/analyze/call-groups": {
"post": {
"operationId": "getCallGroup",
"parameters": [
{
"in": "query",
"name": "fillTimeSeries",
"schema": {
"type": "boolean",
"example": null
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"group": {
"groupbyTag": "service.name",
"groupbyTagEntity": "DESTINATION"
},
"metrics": [
{
"aggregation": "P75",
"metric": "latency",
"granularity": 360
}
],
"includeInternal": false,
"includeSynthetic": false,
"order": {
"by": "calls_SUM",
"direction": "DESC"
},
"pagination": {
"page": 1,
"pageSize": 1
},
"tagFilterExpression": {
"type": "EXPRESSION",
"logicalOperator": "AND",
"elements": [
{
"type": "TAG_FILTER",
"name": "call.type",
"operator": "EQUALS",
"entity": "NOT_APPLICABLE",
"value": "DATABASE"
},
{
"type": "TAG_FILTER",
"name": "service.name",
"operator": "EQUALS",
"entity": "DESTINATION",
"value": "ratings"
}
]
},
"timeFrame": {
"to": "1688366990000",
"windowSize": "600000"
}
},
"schema": {
"$ref": "#/components/schemas/GetCallGroups"
}
}
}
},
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"items": [
{
"name": "ratings",
"timestamp": 1688366520000,
"cursor": {
"@class": ".IngestionOffsetCursor",
"ingestionTime": 1688980829000,
"offset": 1
},
"metrics": {
"latency.p75.360": [
[
1688366520000,
1
]
]
}
}
],
"canLoadMore": false,
"totalHits": 1,
"totalRepresentedItemCount": 1,
"totalRetainedItemCount": 1,
"adjustedTimeframe": {
"windowSize": 360000,
"to": 1688366880000
}
},
"schema": {
"$ref": "#/components/schemas/CallGroupsResult"
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get grouped call metrics",
"tags": [
"Application Analyze"
],
"description": "This endpoint retrieves the metrics for calls.\r\n\r\n## Deprecated Parameters\r\n**tagFilters:** The list of tag filters. It is replaced by **tagFilterExpression**, **includeInternal** and **includeSynthetic**."
}
},
"/api/application-monitoring/analyze/trace-groups": {
"post": {
"operationId": "getTraceGroups",
"parameters": [
{
"in": "query",
"name": "fillTimeSeries",
"schema": {
"type": "boolean",
"example": null
}
}
],
"requestBody": {
"content": {
"application/json": {
"example": {
"group": {
"groupbyTag": "trace.endpoint.name",
"groupbyTagEntity": "NOT_APPLICABLE"
},
"metrics": [
{
"aggregation": "SUM",
"metric": "latency"
}
],
"order": {
"by": "traces_SUM",
"direction": "ASC"
}
},
"schema": {
"$ref": "#/components/schemas/GetTraceGroups"
}
}
}
},
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"items": [
{
"name": "GET /api/cart-total",
"timestamp": 1688542673148,
"cursor": {
"@class": ".IngestionOffsetCursor",
"ingestionTime": 1688543264000,
"offset": 1
},
"metrics": {
"latency.sum": [
[
1688543260000,
31
]
]
}
}
],
"canLoadMore": true,
"totalHits": 2595,
"totalRepresentedItemCount": 2595,
"totalRetainedItemCount": 2595,
"adjustedTimeframe": {
"windowSize": 600000,
"to": 1687939110000
}
},
"schema": {
"$ref": "#/components/schemas/TraceGroupsResult"
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get grouped trace metrics",
"tags": [
"Application Analyze"
]
}
},
"/api/application-monitoring/analyze/traces": {
"post": {
"operationId": "getTraces",
"requestBody": {
"content": {
"application/json": {
"example": {
"tagFilterExpression": {
"type": "EXPRESSION",
"logicalOperator": "AND",
"elements": [
{
"type": "TAG_FILTER",
"name": "endpoint.name",
"operator": "EQUALS",
"entity": "DESTINATION",
"value": "alerting_integrations"
},
{
"type": "TAG_FILTER",
"name": "service.name",
"operator": "EQUALS",
"entity": "NOT_APPLICABLE",
"value": "catalog"
}
]
}
},
"schema": {
"$ref": "#/components/schemas/GetTraces"
}
}
}
},
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"items": [
{
"trace": {
"id": "c11d056d778b4202",
"label": "POST /shipping/anonymous-526093",
"startTime": 1688447998665,
"duration": 2,
"erroneous": false,
"service": {
"id": "8bfb4e1aa590eab8f08f837b97acf5803a5737ed",
"label": "cart",
"types": [],
"technologies": [],
"snapshotIds": [],
"entityType": "SERVICE"
},
"endpoint": null
},
"cursor": {
"@class": ".IngestionOffsetCursor",
"ingestionTime": 1688448014000,
"offset": 1
}
}
],
"canLoadMore": true,
"totalHits": 12393,
"totalRepresentedItemCount": 12393,
"totalRetainedItemCount": 12393,
"adjustedTimeframe": {
"windowSize": 600000,
"to": 1687938300000
}
},
"schema": {
"$ref": "#/components/schemas/TraceResult"
}
}
},
"x-example": "TraceResult"
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get all traces",
"tags": [
"Application Analyze"
],
"x-code-samples": [
{
"lang": "JAVA",
"source": "CloseableHttpClient client = HttpClients.createDefault();\nString url = \"https://unit-tenant.instana.com/api/application-monitoring/analyze/traces\";\nHttpPost httpPost = new HttpPost(url);\nString json = \"{\"\n + \"\\\"pagination\\\":{\\\"retrievalSize\\\":20,\\\"offset\\\":0},\"\n + \"\\\"timeFrame\\\":{\\\"windowSize\\\":3600000}\"\n + \"}\"\nStringEntity entity = new StringEntity(json);\nhttpPost.setEntity(entity);\nhttpPost.setHeader(\"Accept\", \"application/json\");\nhttpPost.setHeader(\"Content-type\", \"application/json\");\nhttpPost.setHeader(\"Authorization\", \"apiToken xxxxxxxx\");\n\nCloseableHttpResponse response = client.execute(httpPost);\n\nassertThat(response.getStatusLine().getStatusCode(), equalTo(200));\nString traceResult = EntityUtils.toString(response.getEntity());\nclient.close();\n"
},
{
"lang": "SHELL",
"source": "curl --request POST \\\n --url https://unit-tenant.instana.io/api/application-monitoring/analyze/call-groups \\\n --header 'authorization: apiToken {apiToken}}' \\\n --header 'content-type: application/json' \\\n --data '{ \n\n\"timeFrame\": { \n\"windowSize\": 36000000 \n}, \n\"order\":{\n\t\"by\": \"errors\", \n\"direction\": \"DESC\" \n},\n\"group\": { \n\"groupbyTag\": \"application.name\"\n}, \n\"metrics\": [ \n{ \n\"metric\": \"errors\", \n\"aggregation\": \"MEAN\" \n} \n] \n} '"
}
],
"description": "This endpoint retrieves the metrics for traces.\r\n\r\n**Manditory Paramters:**\r\n\r\n**Optional Paramters:**\r\n\r\n**Defaults:**\r\n\r\n**Limits:**\r\n\r\n**Tips:**\r\n"
}
},
"/api/application-monitoring/analyze/traces/{id}": {
"get": {
"deprecated": true,
"description": "Replaced by /api/application-monitoring/v2/analyze/traces/{id}",
"operationId": "getTrace",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string",
"example": null
}
}
],
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"id": "c606ccf3578135c6",
"totalErrorCount": 0,
"rootSpan": {
"id": "7757e58f78fff3c8",
"parentId": "",
"foreignParentId": "",
"callId": "7757e58f78fff3c8",
"name": "node.http.server",
"label": "GET /products",
"start": 1688365739882,
"duration": 22,
"calculatedSelfTime": 4,
"errorCount": 0,
"batchSize": 1,
"batchSelfTime": 22,
"kind": "ENTRY",
"isSynthetic": false,
"data": {
"http": {
"rawUrl": "/products",
"path": "/products",
"method": "GET",
"host": "localhost:8000",
"path_tpl": "/products",
"status": 200
}
},
"source": {
"applications": [],
"service": {
"id": "ROOT",
"label": "",
"types": [],
"technologies": [],
"snapshotIds": [],
"entityType": "SERVICE"
},
"endpoint": {
"id": "kVZuxJ7SE8F89iXn6dJ6rdEjQzY",
"label": "Robot-Shop",
"type": "HTTP",
"serviceId": "",
"technologies": [],
"syntheticType": "NON_SYNTHETIC",
"entityType": "ENDPOINT"
},
"physicalContext": {}
},
"destination": {
"applications": [
{
"id": "Jv83WpUmSKiiCWIpi-reSQ",
"label": "Robot-Shop",
"boundaryScope": "INBOUND",
"entityType": "APPLICATION"
},
{
"id": "sYoqGlu8SVy2ILv-4lh5aw",
"label": "All Services",
"boundaryScope": "INBOUND",
"entityType": "APPLICATION"
},
{
"id": "R0ZWCcK1ShiFXEW4JHjTZg",
"label": "node.js Services",
"boundaryScope": "INBOUND",
"entityType": "APPLICATION"
}
],
"service": {
"id": "8939fc2f4b7a964c5c7d40e881daa9d883478be7",
"label": "eum-sim",
"types": [],
"technologies": [],
"snapshotIds": [],
"entityType": "SERVICE"
},
"endpoint": {
"id": "dIgIisQFGd-eVZmYaAwhM5sesPA",
"label": "GET /products",
"type": "HTTP",
"serviceId": "",
"technologies": [],
"syntheticType": "NON_SYNTHETIC",
"entityType": "ENDPOINT"
},
"physicalContext": {
"process": {
"id": "dzP4kVCxYu9o8pcesl2WRAc_lJc",
"time": 1687520911000,
"label": "eum-sim v2.0.0",
"plugin": "nodeJsRuntimePlatform",
"data": null
},
"container": {
"id": "3w4-kfSCVJeSsYv5VFf9OCL0s4I",
"time": 1687520634000,
"label": "eum-sim (eum/eum-sim-7549958c6d-pkx98)",
"plugin": "docker",
"data": null
},
"host": {
"id": "dHBz3ZRZdpsKcXGd-cNuwej-j6Y",
"time": 1688187888000,
"label": "Host-1",
"plugin": "host",
"data": {
"cpu.count": 4,
"os.name": "Linux",
"memory.total": 15729750016
}
}
}
},
"stackTrace": [],
"childSpans": []
}
},
"schema": {
"$ref": "#/components/schemas/FullTrace"
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get trace detail",
"tags": [
"Application Analyze"
]
}
},
"/api/application-monitoring/applications": {
"get": {
"operationId": "getApplications",
"parameters": [
{
"description": "Name of application",
"in": "query",
"name": "nameFilter",
"schema": {
"type": "string",
"example": null
}
},
{
"description": "Size of time window in milliseconds",
"in": "query",
"name": "windowSize",
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
},
{
"description": "Timestamp since Unix Epoch in milliseconds of the end of the time window",
"in": "query",
"name": "to",
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
},
{
"description": "Page number from results",
"in": "query",
"name": "page",
"schema": {
"type": "integer",
"format": "int32",
"example": null
}
},
{
"description": "Number of items per page",
"in": "query",
"name": "pageSize",
"schema": {
"type": "integer",
"format": "int32",
"example": null
}
},
{
"description": "Filter for application scope, i.e: INBOUND or ALL",
"in": "query",
"name": "applicationBoundaryScope",
"schema": {
"type": "string",
"enum": [
"ALL",
"INBOUND"
],
"example": null
}
}
],
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"items": [
{
"boundaryScope": "INBOUND",
"entityType": "APPLICATION",
"id": "e8krH1wNRV6daAo-NEmG8g",
"label": "Robot Shop"
}
],
"page": 1,
"pageSize": 1,
"totalHits": 1
},
"schema": {
"$ref": "#/components/schemas/ApplicationResult"
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get applications",
"tags": [
"Application Resources"
]
}
},
"/api/application-monitoring/applications/services": {
"get": {
"operationId": "getApplicationServices",
"parameters": [
{
"description": "Name of application/service",
"in": "query",
"name": "nameFilter",
"schema": {
"type": "string",
"example": null
}
},
{
"description": "Size of time window in milliseconds",
"in": "query",
"name": "windowSize",
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
},
{
"description": "Timestamp since Unix Epoch in milliseconds of the end of the time window",
"in": "query",
"name": "to",
"schema": {
"type": "integer",
"format": "int64",
"example": null
}
},
{
"description": "Page number from results",
"in": "query",
"name": "page",
"schema": {
"type": "integer",
"format": "int32",
"example": null
}
},
{
"description": "Number of items per page",
"in": "query",
"name": "pageSize",
"schema": {
"type": "integer",
"format": "int32",
"example": null
}
},
{
"description": "Filter for application scope, i.e: INBOUND or ALL",
"in": "query",
"name": "applicationBoundaryScope",
"schema": {
"type": "string",
"enum": [
"ALL",
"INBOUND"
],
"example": null
}
},
{
"description": "Include snapshot ids in the results",
"in": "query",
"name": "includeSnapshotIds",
"schema": {
"type": "boolean",
"example": null
}
}
],
"responses": {
"default": {
"content": {
"application/json": {
"example": {
"items": [
{
"entityType": "SERVICE",
"id": "79f1430f4a42a707a97621ca00617e40bd51c31d",
"label": "www.paypal.com",
"snapshotIds": [
"CywiRxmGIwtQIKezVs-XMcTX2xg"
],
"technologies": [
"kafkaCluster"
],
"types": [
"MESSAGING"
]
}
],
"page": 1,
"pageSize": 1,
"totalHits": 1
},
"schema": {
"$ref": "#/components/schemas/ServiceResult"
}
}
}
}
},
"security": [
{
"ApiKeyAuth": [
"Default"
]
}
],
"summary": "Get applications/services",
"tags": [
"Application Resources"
]
}
},
"/api/application-monitoring/applications/services/endpoints": {