This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Command-line interfacebreadcrumb arrow gql
Experimental Open source

gql

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The gql command runs a GraphQL query against the Alloy GraphQL API. Use this command to query information from a running Alloy instance, such as build metadata, readiness, and component health.

The gql command doesn’t enable the GraphQL API. The target Alloy instance must run with the GraphQL API enabled.

Usage

shell 
alloy gql [<FLAG> ...] <QUERY>

Replace the following:

  • <FLAG>: One or more flags that define the GraphQL endpoint.
  • <QUERY>: Required. The GraphQL query to run.

The graphql command is an alias for gql.

Enable the GraphQL API

The GraphQL API is disabled by default. To enable it, start Alloy with the --stability.level=experimental and --server.http.enable-graphql flags:

shell 
alloy run --stability.level=experimental --server.http.enable-graphql <CONFIG_PATH>

Replace <CONFIG_PATH> with the Alloy configuration file or directory path.

Query formats

The gql command accepts complete GraphQL queries. For example, you can run an anonymous query:

shell 
alloy gql '{ alloy { version isReady } }'

The command also accepts query body shorthand. When the query doesn’t start with {, query, mutation, or subscription, the command wraps it in query { ... }.

For example, the following command:

shell 
alloy gql 'alloy { version isReady }'

Runs this GraphQL query:

graphql 
query { alloy { version isReady } }

Flags

The following flags are supported:

  • --endpoint: Address of the GraphQL endpoint (default "http://127.0.0.1:12345/graphql").

Examples

To query build and readiness information from the default GraphQL endpoint, use the following command:

shell 
alloy gql 'alloy { isReady version }'

The output resembles the following:

JSON 
{
  "data": {
    "alloy": {
      "isReady": true,
      "version": "v1.14.0"
    }
  }
}

To query a GraphQL endpoint on a different address (including other Alloy deployments), use the --endpoint flag:

shell 
alloy gql --endpoint=http://localhost:12345/graphql 'components { id health { message } }'