forked from tailcallhq/tailcallhq.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'develop' into mustache-docs
- Loading branch information
Showing
42 changed files
with
1,245 additions
and
242 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,6 @@ | ||
| { | ||
| "semi": false, | ||
| "printWidth": 120, | ||
| "bracketSpacing": false | ||
| "bracketSpacing": false, | ||
| "overrides": [{"files": "*.md", "options": {"printWidth": 60}}] | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| --- | ||
| title: Apollo Studio | ||
| description: "Learn to enhance your GraphQL server's efficiency by integrating Tailcall with Apollo Studio through our concise guide. Discover how to configure Tailcall to send vital usage metrics to Apollo Studio, enabling advanced performance monitoring and optimization. Whether you're establishing a Monolith graph or improving an existing one, our instructions will facilitate a seamless integration. This guide helps you set up for better insights and also advises on leveraging Apollo Studio's features for a more responsive GraphQL server. Start optimizing today with our straightforward steps, and explore how to access Apollo Studio's free trial for new users." | ||
| --- | ||
|
|
||
| This guide illustrates how to configure `tailcall` to send usage metrics to [Apollo Studio](https://studio.apollographql.com). | ||
|
|
||
| ## Creating a monolith graph | ||
|
|
||
| 1. Before you configure `tailcall`, you will need to create a `Monolith` graph on Apollo Studio. | ||
|
|
||
|  | ||
|
|
||
| 1. Go to your organization's home page and click on `Create your first graph`, if this is your first graph or `Create New Graph` if you have existing graphs. | ||
|
|
||
|  | ||
|
|
||
| 1. Change the `Graph title`, `Graph ID` and other fields as desired and make sure to change `Graph Architecture` to Monolith, assuming `tailcall` is booted in monolith mode. | ||
| 1. Once you are done, click on `Next`. You'll see the following screen. | ||
|
|
||
|  | ||
|
|
||
| 1. Copy the fields `APOLLO_KEY` and `APOLLO_GRAPH_REF` as they are required by `tailcall` to be able to send the usage metrics. | ||
|
|
||
| 1. Next we need to connect Apollo with our running instance of Tailcall. There are two ways to let Apollo know about your GraphQL schema: | ||
|
|
||
| 1. Navigate to `Local Introspection`. If you have a deployed instance of your GraphQL server you can put the URL pointing to that in `Endpoint URL` and click on `Introspect and Upload`. If not, start a local instance of `tailcall` and put the local url here, similar to how is shown in the image below. You can start a local instance of Tailcall by running `tailcall start` (click [here](./cli.md) to know more). | ||
|
|
||
|  | ||
|
|
||
| 1. Or, Navigate to `Local Schema` and insert your schema generated by `tailcall` and click `Upload`. You can get the schema by running `tailcall check` (click [here](./cli.md) to know more). | ||
|
|
||
|  | ||
|
|
||
| You have now created a Monolith graph in Apollo Studio. The next step is to configure `tailcall` to use the `APOLLO_API_KEY` and `APOLLO_GRAPH_REF`. Follow detailed instructions [here](../operators/telemetry.md). | ||
|
|
||
| ## Checking the metrics in Apollo Studio | ||
|
|
||
| To see the metrics for you queries follow these instructions: | ||
|
|
||
| 1. Start `tailcall` with the appropriate configuration for Apollo (click [here](./cli.md#start) to know more). Below is an example of what a config may look like: | ||
|
|
||
| ```graphql | ||
| schema | ||
| @server(port: 8000, graphiql: true) | ||
| @upstream( | ||
| baseURL: "http://jsonplaceholder.typicode.com" | ||
| ) | ||
| @telemetry( | ||
| export: { | ||
| apollo: { | ||
| api_key: "<APOLLO_API_KEY from Apollo Website>" | ||
| graph_ref: "<APOLLO_GRAPH_REF from Apollo Website>" | ||
| } | ||
| } | ||
| ) { | ||
| query: Query | ||
| } | ||
|
|
||
| type Query { | ||
| posts: [Post] @http(path: "/posts") | ||
| } | ||
|
|
||
| type Post { | ||
| id: Int! | ||
| userId: Int! | ||
| title: String! | ||
| body: String! | ||
| } | ||
| ``` | ||
|
|
||
| 1. Visit `http://localhost:8000/graphql` and create a query with an appropriate name (below is an example query named `MyQuery`) and run it multiple times to send the metrics to Apollo Studio. | ||
|
|
||
| :::tip | ||
| Naming the query is not required to be able to send the metrics, but it helps to organize the metrics with appropriate names when viewed in Apollo Studio. | ||
| ::: | ||
|
|
||
| ```graphql | ||
| query MyQuery { | ||
| posts { | ||
| id | ||
| title | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 1. To see the metrics click on the `VARIANT NAME` of your graph. In the example below, the variant name is `current`. | ||
|
|
||
|  | ||
|
|
||
| 1. You will see the following page. From here click on insights icon as highlighted on the left side of the image. | ||
|
|
||
|  | ||
|
|
||
| 1. You will now be able to see all the information related to your queries here | ||
|
|
||
|  | ||
|
|
||
|  | ||
|
|
||
| :::important | ||
| If you don't see the name of your query here, try running the query multiple times and waiting for some time. Since the metric isn't sent to Apollo Studio for each query, instead they are batched together and sent at once for efficiency reasons. | ||
| ::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,94 +1,104 @@ | ||
| --- | ||
| title: Context | ||
| title: Context Overview | ||
| description: "Explore Tailcall's dynamic Context mechanism for schema field resolution, enabling access to arguments, values, and environment variables for efficient GraphQL queries. Tailcall, GraphQL, Context, dynamic resolution, schema fields, environment variables, query arguments." | ||
| --- | ||
|
|
||
| In any GraphQL framework, including Tailcall, `Context` serves as a fundamental mechanism for sharing data across different parts of your application. This adaptable object becomes available to every resolver in GraphQL. | ||
| Within Tailcall, `Context` is a pivotal component that allows for dynamic retrieval of values during the resolution of fields for a given type within the schema. | ||
|
|
||
| ## Context in Tailcall | ||
|
|
||
| In Tailcall, as in all GraphQL implementations, every [Operator](operators/index.md) can access Context. Operators use Context to store and retrieve data necessary for shared operations. | ||
|
|
||
| You can describe the Context with the following Typescript interface: | ||
| ## Schema Definition | ||
|
|
||
| ```typescript | ||
| interface Context { | ||
| args: Map<string, Json> | ||
| value: Json | ||
| parent: Context | ||
| type Context = { | ||
| args: Map<string, JSON> | ||
| value: JSON | ||
| env: Map<string, string> | ||
| vars: Map<string, string> | ||
| headers: Map<string, string> | ||
| } | ||
| ``` | ||
| `Context` operates by storing values as key-value pairs, which can be accessed through mustache template syntax. | ||
| ### args | ||
| These arguments pass to the current query, allowing access to the query's arguments. For example, | ||
| This property facilitates access to query arguments. Consider the example: | ||
| ```graphql showLineNumbers | ||
| type Query { | ||
| user(id: ID!): User @http(path: "/users/{{args.id}}") | ||
| } | ||
| ``` | ||
|
|
||
| In this example, you use `args.id` to access the `id` argument passed to the `user` query. | ||
| Here, `args.id` is utilized to retrieve the `id` argument provided to the `user` query. | ||
|
|
||
| ### value | ||
|
|
||
| This field represents the value of the current node. For instance, | ||
| This enables access to the fields of the specified type. | ||
|
|
||
| ```graphql showLineNumbers | ||
| ```graphql showlineNumbers | ||
| type Post { | ||
| id: ID! | ||
| title: String! | ||
| body: String! | ||
| comments: [Comment] @http(path: "/posts/{{value.id}}/comments") | ||
| comments: [Comment] | ||
| @http(path: "/posts/{{value.id}}/comments") | ||
| } | ||
| ``` | ||
|
|
||
| Here, `value.id` provides access to the `id` field of the `Post` type. | ||
| In this case, `value.id` accesses the `id` field of the `Post` type. | ||
|
|
||
| ### parent | ||
| ### env | ||
|
|
||
| Environment variables, set at server startup, allow directives to dynamically adapt behavior based on external configurations without altering the server configuration itself. | ||
|
|
||
| This field indicates the context of the parent node. | ||
| Example: | ||
|
|
||
| ```graphql showLineNumbers | ||
| type Query { | ||
| posts: [Post] @http(path: "/posts") | ||
| } | ||
| type Post { | ||
| id: Int! | ||
| userId: Int! | ||
| title: String! | ||
| body: String! | ||
| user: User | ||
| @http(path: "/users", query: [{key: "id", value: "{{value.userId}}"}], matchPath: ["id"], matchKey: "userId") | ||
| users: [User]! | ||
| @http(baseUrl: "{{env.API_ENDPOINT}}", path: "/users") | ||
| } | ||
| ``` | ||
|
|
||
| In this scenario, `value.userId` helps retrieve the `userId` information from the "parent" context of the `Post` type, effectively extracting a list of `userId` fields from the `Post` types. Consider `value` as a container holding the results of a post query, with `userId` as the specific key you want to extract. | ||
| `env.API_ENDPOINT` references an environment variable named `API_ENDPOINT`, which specifies the base URL for HTTP requests. | ||
|
|
||
| ### env | ||
| ### vars | ||
|
|
||
| This field represents global environment variables for the server, set once when the server starts. | ||
| `vars` offers a mechanism for defining reusable variables within the configuration. Unlike `env`, these are embedded and can be universally applied across configurations. | ||
|
|
||
| ```graphql showLineNumbers | ||
| schema | ||
| @server( | ||
| vars: {key: "apiKey", value: "{{env.AUTH_TOKEN}}"} | ||
| ) { | ||
| query: Query | ||
| } | ||
|
|
||
| type Query { | ||
| users: [User]! @http(baseUrl: "{{env.API_ENDPOINT}}", path: "/users") | ||
| user(id: ID!): [User] | ||
| @http( | ||
| url: "/users" | ||
| headers: [ | ||
| { | ||
| key: "Authorization" | ||
| value: "Bearer {{vars.apiKey}}" | ||
| } | ||
| ] | ||
| ) | ||
| } | ||
| ``` | ||
|
|
||
| Here, `env.API_ENDPOINT` refers to an environment variable named API_ENDPOINT, defined in your server settings. | ||
| Here, the variable `apiKey` is set using an environment variable and subsequently utilized in the `Authorization` header for HTTP requests. | ||
|
|
||
| ### headers | ||
|
|
||
| These headers come from the request received by the Tailcall server. | ||
| Headers originate from the request made to the Tailcall server. | ||
|
|
||
| ```graphql showLineNumbers | ||
| type Query { | ||
| commentsForUser: [Comment] @http(path: "/users/{{headers.userId}}/comments") | ||
| commentsForUser: [Comment] | ||
| @http(path: "/users/{{headers.x-user-id}}/comments") | ||
| } | ||
| ``` | ||
|
|
||
| Here, `headers.userId` refers to a header called `userId` that should be present in the `context`. The server can use this `userId` to fetch comments for the specified user. | ||
|
|
||
| [operator]: /docs/operators | ||
| In this example, `headers.x-user-id` extracts the value of the `x-user-id` header present in the request, dynamically constructing the request path. |
Oops, something went wrong.