Oracle Management Cloud APM REST API

Applications

In the Application Performance Monitoring System an Application object (sometimes called an Application Definition, or simply an Application) is used to group and organize Pages, Ajax Calls, Server Requests, Application Servers and other resources, that are related to one another through the definition of the Application.

In the context of this REST API, the Application object is similar, but different, to the applications you are monitoring using APMCS. You may choose to construct the definition of your Application object so that it exactly matches your understanding of your entire application, starting with your application's website's home page, and, via APMCS, gathering all related pages, services and resources.

The REST API Application object is expressed in terms of seed rules. These rules determine the starting points for finding related items in the application's data flow discovered by APMCS. Starting with the seed rule the system will apply that rule to find the seed objects, and then, following the data flow trail of those objects, find the other objects that are in that flow. Eventually, all objects that originate directly and indirectly from the seed object will be part of the Application defined by your seed rule.

For example, let's start with a single seed rule that identifies a particular page in a website, such as the following (the rule syntax will be explained soon):

FLOWS WITH PAGES MATCHING (pageURL LIKE '%http://hostA:1111/acmeShopping1/%')

This rule will locate the identified page - the seed object. This object will likely lead to different server requests that originated from the page synchronously, or asynchronously via an Ajax call, and those requests may make requests of other services. Eventually, all entities that are discovered along the flow will become part of this Application - they are all related in that they originated from the page seed object, identified by the Application's seed rule. The entities can include any entities discussed elsewhere in this documentation - server requests, pages, application servers, JVMs, databases, thread pools, etc.

REST API queries that that involve an Application can be considered a filtering mechanism which selects related objects that can be retrieved and viewed. The metric data returned for any object that is retrieved within the context of an Application object, is the identical metric data that would have been returned had it been retrieved directly via the REST API.

Creating an Application

To create an application you need to give it a name and a seed rule. This rule will identify the seed object which can be considered the starting object of your application. This seed object may be a web page or a server request, and the seed rule is either a page-rule or a server-request-rule.

In order to better understand the syntax for the seed rule described next you may want to review the description of Filters, specifically the sections describing the Filter Expression Syntax and the Metadata Filter Attributes, both of which are used here to build the seed rule.

page-rule Syntax

The page-rule syntax is:

    FLOWS WITH PAGES MATCHING page-rule-expression
    where page-rule-expression is a filter-expression for the /pages resource

The page-rule is best shown with some examples:

    FLOWS WITH PAGES MATCHING (pageURL LIKE '%http://hostA:7819/acmeShopping/%')
    FLOWS WITH PAGES MATCHING (pageTitle LIKE 'AcmeStartPage')
    FLOWS WITH PAGES MATCHING ((pageTitle LIKE 'AcmeStartPage') AND (averageResponseTime >= 3000))

The different attribute names (and their data types) that may be used with the page-rule-expression can be found by querying the /metadata resource (the Get metadata operation) with the Filter type parameter and the /pages resource type.

/api/v1/metadata/Filter/pages

In our examples just above we used the pageURL, pageTitle and averageResponseTime attributes to construct our sample page-rules.

server-request-rule Syntax

The server-request-rule syntax is:

    FLOWS WITH FIRST SERVER REQUEST MATCHING server-request-rule-expression
    where server-request-rule-expression is a filter-expression for the /requests resource

The server-request-rule is also shown with some examples:

    FLOWS WITH FIRST SERVER REQUEST MATCHING (serverName ILIKE '%HostApp1%')
    FLOWS WITH FIRST SERVER REQUEST MATCHING ((deploymentName ILIKE '%OrderService.war%') AND (operationName LIKE 'OrderService.submit'))

The different attribute names (and their data types) that may be used with the server-request-rule-expression can be found by querying the /metadata resource (the Get metadata operation) with the Filter type parameter and the /requests resource type.

/api/v1/metadata/Filter/requests

In our examples just above we used the serverName, deploymentName and operationName attributes to construct our server-request-rules.

Application JSON Payload

Now that we are familiar with the page-rule and server-request-rule syntax let's put it together in JSON. We'll create a simple AcmeApp that uses the AcmeHomePage page as its seed rule. Later we'll use this JSON as our payload with a cURL command:

    {
    "applicationName" : "AcmeApp",
    "applicationRules" : [
    "FLOWS WITH PAGES MATCHING (pageURL ILIKE '%AcmeHomePage%')"
    ]
    }

Note that the application is created with a name and a single seed rule. The actual rule is en element of the applicationRules array. Though this is an array, currently the array must contain only one rule.

Creating an Application using cURL

We've created the JSON definition of our application and we now we want to execute it. All examples in this REST API document use cURL, so we'll use that together with our JSON payload that we edited above. Most other examples, use the HTTP GET verb. To create the application we'll use POST verb. We'll POST the JSON to the /api/v1/applications resource.

Since this command generates no JSON response, we'll add the -i command line option to include the HTTP header on the cURL output. Without that we may not know if the command failed or not. For the special cURL command return codes for Application objects, see the Status Codes for Application Operations section in the HTTP Response Status Codes page.

Also, to avoid problems with string quotes when used on the command line with OS shell scripts, we'll save our JSON definition above, in a local file called acmeAppDef.json. In order to tell cURL about our JSON payload we'll pass the file on the command line using the -d (data) command line option with a -H (header) specifying that this is JSON data.

The following example command line puts this all together. The interesting parts of the command line are in bold:

curl
    -i -X POST -d @acmeAppDef.json -H "Content-type:application/json"
    --insecure -H "X-USER-IDENTITY-DOMAIN-NAME: apm_testtenantx1" -u 'apm_testtenantx1.emcsadmin:Welcome1!'
    'https://slc04baq.us.oracle.com:4443/serviceapi/apm.dataserverQaEnv/api/v1/applications'

The command line above is an example of the Create application operation.

The HTTP output of this command is:

HTTP/1.1 201 Created
    Date: Tue, 23 Feb 2016 20:33:39 GMT
    X-Frame-Options: SAMEORIGIN
    Content-Length: 0
    Content-Type: application/json
    X-ORACLE-DMS-ECID: 005B7NTyOwSDGfQ_I_P5if0006Jl0000K_
    Set-Cookie: EMCS_JSESSIONID=FkYP1lnLltWifdF5MVoD_ZKYA9MX8TDDWIU2E9E4MgGAX-ReDWrP!-1052259951; expires=Tue, 23-Feb-2016 20:33:49 GMT; path=/apmcs/data; secure; HttpOnly
    Set-Cookie: _WL_AUTHCOOKIE_EMCS_JSESSIONID=DnwsiKqBHzdHJJdiZYSJ; path=/apmcs/data; secure; HttpOnly
    Cache-Control: no-cache,no-store
    Content-Language: en

Using an Application

Once an application has been created, the application may be retrieved and used. For example you may retrieve all the applications (Get application definitions), or a named application (Get named application definition). Retrieving the application objects merely retrieves application definitions without any metric data.

WITHIN APPLICATION Filter

The most interesting use of an application is to retrieve metric data within the scope of that application; basically, monitoring the entities that make up the application. This is accomplished using the filter expression (the q parameter) that can be added to nearly every operation that retrieves metric data (filter expressions are explained in the Filter Results overview).

The filter expression to retrieve metric data of entities that are in an application is:

q=WITHIN APPLICATION application-name

For example, to retrieve all the pages that are part of the previously created AcmeApp application object, you can use the following query (notice that spaces are encoded with %20):

/api/v1/pages?q=WITHIN%20APPLICATION%20AcmeApp

The metric data returned for these pages are the same as the data that would have been retrieved had you listed the pages directly through some other query. In essence, the application object allows you to create a virtual family of pages that are related through the application.

Another example may retrieve all application servers in our AcmeApp application, ordered by peak usage:

api/v1/appservers/?q=WITHIN%20APPLICATION%20AcmeApp&since=2016-02-21T00:00:00.000Z&until=2016-02-22T00:32:00.000Z&orderBy=peakUsedOfMaxPct:desc

Deleting an Application

To delete an application you use the HTTP DELETE verb for cURL (Delete application definition). The command line specifies the application you intend to delete (/api/v1/applications/AcmeApp)

Note that here too, since this command generates no JSON response, we'll add the -i command line option to include the HTTP header on the cURL output, so that we can determine if the command failed or not:

curl -i -X DELETE
    --insecure -H "X-USER-IDENTITY-DOMAIN-NAME: apm_testtenantx1" -u 'apm_testtenantx1.emcsadmin:Welcome1!'
    'https://slc04baq.us.oracle.com:4443/serviceapi/apm.dataserverQaEnv/api/v1/applications/AcmeApp'

The HTTP output of this command is:

HTTP/1.1 204 No Content
Date: Tue, 23 Feb 2016 20:37:28 GMT
X-Frame-Options: SAMEORIGIN
Content-Type: application/json
X-ORACLE-DMS-ECID: 005B7Nfavn4DGfQ_I_P5if0006Jl0001m6
Set-Cookie: EMCS_JSESSIONID=VIYP2dgpmGGGVx2nZfLwa7WVhgcUYanjik4d0PtqdrBcxRA7KWqi!-1052259951; expires=Tue, 23-Feb-2016 20:37:38 GMT; path=/apmcs/data; secure; HttpOnly
Set-Cookie: _WL_AUTHCOOKIE_EMCS_JSESSIONID=2t1HYiwlBK2xcbwl2DX0; path=/apmcs/data; secure; HttpOnly
Cache-Control: no-cache,no-store
Content-Length: 0
Content-Language: en