Skip to content

Commit e1db20e

Browse files
spawniaspawnia
committed
feat!: Restructure options and describe upgrade process
1 parent 0467c85 commit e1db20e

File tree

5 files changed

+264
-82
lines changed

5 files changed

+264
-82
lines changed

‎README.md‎

Lines changed: 86 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -39,79 +39,103 @@ const client = new ApolloClient({
3939
```
4040

4141
## Options
42-
```js
43-
const defaultOptions = {
42+
```typescript
43+
export interface FullOptions {
44+
/**
45+
* Determines if the given operation should be handled or discarded.
46+
*
47+
* If undefined, all operations will be included.
48+
*/
49+
shouldHandleOperation: undefined | ((operation: Operation) => boolean);
50+
51+
/**
52+
* The uri of the GraphQL endpoint.
53+
*
54+
* Used to add context information, e.g. to breadcrumbs.
55+
*/
56+
uri: undefined | string;
57+
58+
/**
59+
* Set the Sentry transaction name to the GraphQL operation name.
60+
*
61+
* May be overwritten by other parts of your app.
62+
*/
63+
setTransaction: true | false;
64+
65+
/**
66+
* Narrow Sentry's fingerprint by appending the GraphQL operation name to the {{default}} key.
67+
*
68+
* Only the last executed operation will be added, not every operation that's been through the link.
69+
* May be overwritten by other parts of your app.
70+
*/
71+
setFingerprint: true | false;
72+
73+
/**
74+
* Attach a breadcrumb for executed GraphQL operations.
75+
*
76+
* The following information will be included by default:
77+
* {
78+
* type: 'http',
79+
* category: `graphql.${operationType}`,
80+
* message: operationName,
81+
* level: errors ? 'error' : 'info',
82+
* }
83+
*/
84+
attachBreadcrumbs: AttachBreadcrumbsOptions | false;
85+
}
86+
87+
export type AttachBreadcrumbsOptions = {
88+
/**
89+
* Include the full query string?
90+
*/
91+
includeQuery: false | true;
92+
93+
/**
94+
* Include the variable values?
95+
*
96+
* Be careful not to leak sensitive information or send too much data.
97+
*/
98+
includeVariables: false | true;
99+
100+
/**
101+
* Include the fetched result (data, errors, extensions)?
102+
*
103+
* Be careful not to leak sensitive information or send too much data.
104+
*/
105+
includeFetchResult: false | true;
106+
44107
/**
45-
* Set the Sentry `transaction` to the `operationName` of the query / mutation. Note that this
46-
* only works if the transaction is not overwritten later in your app.
108+
* Include the response error?
109+
*
110+
* Be careful not to leak sensitive information or send too much data.
47111
*/
48-
setTransaction: true,
112+
includeError: false | true;
49113

50114
/**
51-
* Narrow Sentry's fingerprint by appending the operation's name to Sentry's {{default}} key.
52-
* It works in such a way that only the last operation is added, not every operation that's been
53-
* through the link. Note that if you override this somewhere else in your app, it is possible
54-
* that the value set by `apollo-link-sentry` is overwritten.
115+
* Include the contents of the Apollo Client cache?
116+
*
117+
* This is mostly useful for debugging purposes and not recommended for production environments,
118+
* see "Be careful what you include", unless carefully combined with `beforeBreadcrumb`.
55119
*/
56-
setFingerprint: true,
57-
58-
breadcrumb: {
59-
/**
60-
* Set to false to disable attaching GraphQL operations as breadcrumbs. If only this breadcrumb
61-
* option is toggled, the breadcrumb will only show the operation name and it's type.
62-
*/
63-
enable: true,
64-
65-
/**
66-
* Include the query / mutation string in the breadcrumb.
67-
*/
68-
includeQuery: false,
69-
70-
/**
71-
* Include the entire Apollo cache in the breadcrumb. It is not recommended to enable this
72-
* option in production environment, for several reasons, see "Be careful what you include".
73-
* This option is specifically useful for debugging purposes, but when applied in combination
74-
* with `beforeBreadcrumb` can also be used in production.
75-
*/
76-
includeCache: false,
77-
78-
/**
79-
* Include the operation's variables in the breadcrumb. Again, be careful what you include,
80-
* or apply a filter.
81-
*/
82-
includeVariables: false,
83-
84-
/**
85-
* Include the operation's fetch result in the breadcrumb.
86-
*/
87-
includeResponse: false,
88-
89-
/**
90-
* If an error is received, it can be included in the breadcrumb. Regardless of this option,
91-
* the breadcrumb's type is set to error to reflect a failed operation in the Sentry UI.
92-
*/
93-
includeError: false,
94-
95-
/**
96-
* Include context keys as extra data in the breadcrumb. Accepts dot notation.
97-
* The data is stringified and formatted. Can be used to include headers for instance.
98-
*/
99-
includeContextKeys: [],
100-
},
120+
includeCache: false | true;
101121

102122
/**
103-
* Provide a callback function which receives an instance of this package's Operation class
104-
* Only operations that pass the test are sent to Sentry. Leave undefined if you want all
105-
* operations to pass. See PR #9 for more details.
123+
* Include arbitrary data from the `ApolloContext`?
124+
*
125+
* Accepts a list of keys in dot notation, e.g. `foo.bar`. Can be useful to include extra
126+
* information such as headers.
106127
*/
107-
filter: (operation) => true,
128+
includeContext: false | NonEmptyArray<string>;
108129

109130
/**
110-
* Provide a callback function which receives an instance of this package's OperationBreadcrumb class
111-
* Use it to modify the data that is added to the breadcrumb. Leave undefined if you want all
112-
* data to be included. Very useful in combination with options like includeVariables and includeContextKeys.
131+
* Modify the breadcrumb right before it is sent.
132+
*
133+
* Can be used to add additional data from the operation or clean up included data.
134+
* Very useful in combination with options like `includeVariables` and `includeContextKeys`.
113135
*/
114-
beforeBreadcrumb: (breadcrumb) => breadcrumb,
136+
transform:
137+
| undefined
138+
| ((breadcrumb: GraphQLBreadcrumb, operation: Operation) => Breadcrumb);
115139
};
116140
```
117141

‎UPGRADE.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Upgrade guide
2+
3+
This document provides guidance for upgrading between major versions of `apollo-link-sentry`.
4+
5+
## v2 to v3
6+
7+
### Adapt your configuration
8+
9+
The configuration of `SentryLink` has changed.
10+
11+
```diff
12+
import { SentryLink } from 'apollo-link-sentry';
13+
14+
new SentryLink({
15+
- filter: (operation) => ...,
16+
+ shouldHandleOperation: (operation) => ...,
17+
+ uri: 'https://example.com/graphql',
18+
setTransaction: true,
19+
setFingerprint: true,
20+
21+
- breadcrumb: {
22+
- enable: true,
23+
+ attachBreadcrumbs: {
24+
includeQuery: false,
25+
includeVariables: false,
26+
- includeFetchResult: false,
27+
+ includeFetchResult: false,
28+
includeError: false,
29+
includeCache: false,
30+
- includeContext: ['example'],
31+
+ includeContext: ['example'],
32+
+ transform: (breadcrumb, operation) => ...,
33+
},
34+
- beforeBreadcrumb: (breadcrumb) => ...,
35+
})
36+
```

‎src/index.ts‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1-
export { Operation } from './Operation';
2-
export * from './excludeGraphQLFetch';
3-
export * from './SentryLink';
1+
export { SentryLink } from './SentryLink';
2+
export { SentryLinkOptions } from './options';
3+
export { GraphQLBreadcrumb } from './breadcrumb';
4+
export {
5+
excludeGraphQLFetch,
6+
withoutGraphQLFetch,
7+
} from './excludeGraphQLFetch';

‎src/options.ts‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
import { Operation } from '@apollo/client/core';
2+
import { Breadcrumb } from '@sentry/types';
3+
import deepMerge from 'deepmerge';
4+
5+
import { GraphQLBreadcrumb } from './breadcrumb';
6+
7+
export type NonEmptyArray<T> = [T, ...Array<T>];
8+
9+
export interface FullOptions {
10+
/**
11+
* Determines if the given operation should be handled or discarded.
12+
*
13+
* If undefined, all operations will be included.
14+
*/
15+
shouldHandleOperation: undefined | ((operation: Operation) => boolean);
16+
17+
/**
18+
* The uri of the GraphQL endpoint.
19+
*
20+
* Used to add context information, e.g. to breadcrumbs.
21+
*/
22+
uri: undefined | string;
23+
24+
/**
25+
* Set the Sentry transaction name to the GraphQL operation name.
26+
*
27+
* May be overwritten by other parts of your app.
28+
*/
29+
setTransaction: true | false;
30+
31+
/**
32+
* Narrow Sentry's fingerprint by appending the GraphQL operation name to the {{default}} key.
33+
*
34+
* Only the last executed operation will be added, not every operation that's been through the link.
35+
* May be overwritten by other parts of your app.
36+
*/
37+
setFingerprint: true | false;
38+
39+
/**
40+
* Attach a breadcrumb for executed GraphQL operations.
41+
*
42+
* The following information will be included by default:
43+
* {
44+
* type: 'http',
45+
* category: `graphql.${operationType}`,
46+
* message: operationName,
47+
* level: errors ? 'error' : 'info',
48+
* }
49+
*/
50+
attachBreadcrumbs: AttachBreadcrumbsOptions | false;
51+
}
52+
53+
export type AttachBreadcrumbsOptions = {
54+
/**
55+
* Include the full query string?
56+
*/
57+
includeQuery: false | true;
58+
59+
/**
60+
* Include the variable values?
61+
*
62+
* Be careful not to leak sensitive information or send too much data.
63+
*/
64+
includeVariables: false | true;
65+
66+
/**
67+
* Include the fetched result (data, errors, extensions)?
68+
*
69+
* Be careful not to leak sensitive information or send too much data.
70+
*/
71+
includeFetchResult: false | true;
72+
73+
/**
74+
* Include the response error?
75+
*
76+
* Be careful not to leak sensitive information or send too much data.
77+
*/
78+
includeError: false | true;
79+
80+
/**
81+
* Include the contents of the Apollo Client cache?
82+
*
83+
* This is mostly useful for debugging purposes and not recommended for production environments,
84+
* see "Be careful what you include", unless carefully combined with `beforeBreadcrumb`.
85+
*/
86+
includeCache: false | true;
87+
88+
/**
89+
* Include arbitrary data from the `ApolloContext`?
90+
*
91+
* Accepts a list of keys in dot notation, e.g. `foo.bar`. Can be useful to include extra
92+
* information such as headers.
93+
*/
94+
includeContext: false | NonEmptyArray<string>;
95+
96+
/**
97+
* Modify the breadcrumb right before it is sent.
98+
*
99+
* Can be used to add additional data from the operation or clean up included data.
100+
* Very useful in combination with options like `includeVariables` and `includeContextKeys`.
101+
*/
102+
transform:
103+
| undefined
104+
| ((breadcrumb: GraphQLBreadcrumb, operation: Operation) => Breadcrumb);
105+
};
106+
107+
export const defaultOptions = {
108+
shouldHandleOperation: undefined,
109+
uri: undefined,
110+
setTransaction: true,
111+
setFingerprint: true,
112+
113+
attachBreadcrumbs: {
114+
includeQuery: false,
115+
includeVariables: false,
116+
includeFetchResult: false,
117+
includeError: false,
118+
includeCache: false,
119+
includeContext: false,
120+
transform: undefined,
121+
},
122+
} as const;
123+
124+
export function withDefaults(options: SentryLinkOptions): FullOptions {
125+
return deepMerge(defaultOptions, options);
126+
}
127+
128+
export type SentryLinkOptions = Partial<
129+
Pick<
130+
FullOptions,
131+
'shouldHandleOperation' | 'uri' | 'setTransaction' | 'setFingerprint'
132+
>
133+
> & {
134+
attachBreadcrumbs?: Partial<AttachBreadcrumbsOptions> | false;
135+
};

‎tests/stubs/enableAllOptions.ts‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

0 commit comments

Comments
 (0)