Ce contenu n'est pas disponible dans la langue sélectionnée.
Chapter 2. GraphQL API
The GraphQL API endpoint, /api/v2.2/graphql, automatically runs shorter and simpler queries against target JVMs. These queries can run against a target JVM’s active and archived recordings. Additionally, the API can run queries against general Cryostat archives. You can customize the queries to automate the following tasks for active or archived recordings:
You can customize the queries to automate the following tasks for active or archived recordings:
- Archive
- Delete
- Start
- Stop
When creating a custom query, you must specify specific information for the GraphQL API endpoint in your query. A POST request can then handle the information and send the information to Cryostat. The following example specifies information for the Graph QL API:
POST /api/beta/graphql HTTP/1.1
Accept: application/json, /;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 171
Content-Type: application/json
Host: localhost:8181
User-Agent: HTTPie/3.1.0The GraphQL API is more powerful than the HTTP REST API, which has limited workload capabilities. For example, the HTTP REST API would require you to create an API request for each copy of a recording that you want to start on each scaled replica that is inside a container on OpenShift. The GraphQL API can achieve this task in one API request, which improves the API’s performance and reduces any network traffic for your Cryostat instance.
Another limited workload capability for the HTTP REST API is that this API requires more user intervention, such as requiring you to write custom clients to parse API JSON responses when performing iterative actions on response data. The GraphQL API does not require you to complete this operation.
Additional resources
See Introduction to GraphQL (GraphQL)
2.1. Custom query creation with the GraphQL API
You can use an HTTP client, such as HTTPie, to interact with the GraphQL API for generating custom queries.
When using the API to create a query, you must specify specific values for data types and fields, so that a function can use these values to accurately locate the data you require.
Consider a use case where you could automate a workflow that performs multiple operations in a single query. As an example, an HTTPie client request could send a query to Cryostat so that Cryostat could perform the following tasks:
- Take snapshot recordings of all your target JVM applications.
- Copy recording information from each application into the Cryostat archive.
- Create an automated rule that automatically starts a continuous monitoring recording for any detected target JVM applications.
Many querying possibilities exist, so ensure you accurately determine values for the data types and fields of a query. Otherwise, you might get query results that do not match your requirements.
The following examples demonstrate using the HTTP client to interact with the GraphQL API for generating a simple query and a complex query on Cryostat data.
Example of a simple query for determining all known target JVMs that interact with a Cryostat instance
$ https :8181/api/v1/targets
HTTP/1.1 200 OK
content-encoding: gzip
content-length: 223
content-type: application/json
{
targetNodes {
name
nodeType
labels
target {
alias
serviceUri
}
}
}
The previous example sets specific values for the targetNodes element, such as name. After you run the query, the query returns a list of any target JVMs that match the criteria specified.
Example of a complex query for determining all target applications visible to a Cryostat instance that belong to a particular pod
$ https -v :8181/api/v2.2/graphql query=@graphql/target-nodes-query.graphql
POST /api/v2.2/graphql HTTP/1.1
Accept: application/json, /;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 171
Content-Type: application/json
Host: localhost:8181
User-Agent: HTTPie/2.6.0
{
environmentNodes(filter: { name: "<application_pod_name>" }) {
descendantTargets {
doStartRecording(recording: {
name: "myrecording",
template: "Profiling",
templateType: "TARGET",
duration: 30
}) {
name
state
}
}
}
}
The previous example sets the following specific values for the environmentNodes element, and the example does not return JVM target applications:
-
<application_pod_name>: ensures the query targets a specific pod that operates in the same namespace as Cryostat. -
The
descendantTargets: Provides an array of JVM target objects. -
doStartRecording: The GraphQL API starts JFR recording for each target JVM that the query lists.
After you run the query, the query returns information about the JFR recording that you started, such as a list of active application nodes.
For Red Hat OpenShift, this query would return Deployment and DeploymentConfig API objects, and pods that interact with Cryostat.
The complex query demonstrates how the GraphQL API can perform a single API request that returns any JVM objects that interact with Cryostat and Red Hat OpenShift. The API request then starts a JFR recording on those returned objects.
