Skip to content

Adds one line description and key queries in README #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 25, 2020
Merged

Adds one line description and key queries in README #21

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
322f62b
added general purpose queries in readme along with one line description
JBAhire Aug 24, 2020
3fab144
updated formatting
JBAhire Aug 24, 2020
0b13c58
updated queries as per suggestions
JBAhire Aug 25, 2020
b4f105a
updated queries
JBAhire Aug 25, 2020
e5a7730
added limit to find all traces query
JBAhire Aug 25, 2020
6b96d0c
addressed SJ's and Adrian's comments
JBAhire Aug 25, 2020
871bed3
addressed Adrian's comments
JBAhire Aug 25, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 149 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Hypertrace GraphQL

Hypertrace GraphQL service serves the GraphQL API which will be used by Hypertrace UI.

## Testing

Expand All @@ -9,7 +9,153 @@

`./gradlew run`

## Ports
## Queries
Here are some of the important GraphQL queries:

### 1. Get all traces in provided time range

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d\
Copy link
Contributor

@aaron-steinfeld aaron-steinfeld Aug 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I think it's pretty uncommon to use curl to interface with graphql, although of course workable. I would suspect most readers would use a graphql client. That is to say, the curl part of the doc feels like just noise to me and I think we can just document the queries.

Copy link
Contributor

@codefromthecrypt codefromthecrypt Aug 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Until we have a proper user capable api, I think this is better than nothing as currently people use the zipkin or jaeger apis to poke their systems

We will be using the trace ID and the trace in time range ones for testing, so these two are helpful for examples. It took a very long time to even figure these out. I actually was unable to find anyone who used GraphQL before.

Granted some of the ancillary, repetitive queries could easily be grouped up. Ex get entity name: example of api, endpoint, backend. Agree on that for sure.. pruning sounds fine!

Copy link
Contributor

@aaron-steinfeld aaron-steinfeld Aug 26, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Definitely better than nothing! I guess it gets more to the purpose here - if trying to give a one liner sanity check for things like a health check, curl makes sense- everyone has it and can just copy paste.

If trying to actually work with graphql, there are many interactive clients that are much easier to work with and make things discoverable, include the schema etc. So I guess the primitives I'd expect in the docs are the queries more than the curl commands. Anyway, a nit.

image

'{
traces(
type: API_TRACE
limit: 10
between: {
startTime: "2015-01-01T00:00:00.000Z"
endTime: "2025-01-01T00:00:00.000Z"
}
) {
results {
id
}
}
}'
```

### 2. Verify trace exists

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d \
'{
traces(
type: API_TRACE
between: {
startTime: "2015-01-01T00:00:00.000Z"
endTime: "2025-01-01T00:00:00.000Z"
}
filterBy: [
{
operator: EQUALS
value: "348bae39282251a5"
type: ID
idType: API_TRACE
}
]
) {
results {
apiName: attribute(key: "apiName")
Copy link
Contributor

@codefromthecrypt codefromthecrypt Aug 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this attribute might not be around I think.

}
}
}'
```

### 3. Get all service names

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d \
'{
entities(
type: SERVICE
between: {
startTime: "2015-01-01T00:00:00Z"
endTime: "2025-01-01T00:00:00Z"
}
) {
results {
name: attribute(key: "name")
}
total
}
}'
```

### 4. Get all backend names

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d \
'{
entities(
type: BACKEND
between: {
startTime: "2015-01-01T00:00:00Z"
endTime: "2025-01-01T00:00:00Z"
}
) {
results {
name: attribute(key: "name")
}
total
}
}'
```

### 5. Get all API names

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d \
'{
entities(
type: API
between: {
startTime: "2015-01-01T00:00:00Z"
endTime: "2025-01-01T00:00:00Z"
}
) {
results {
name: attribute(key: "name")
}
total
}
}'
```

GraphQL Service runs on port 23431 at `/graphql` by default
### 6. Get service and backend dependency graph

```graphql
curl -s localhost:2020/graphql -H 'Content-Type: application/graphql' -d \
'{
entities(
type: SERVICE
between: {
startTime: "2015-01-01T00:00:00.000Z"
endTime: "2025-01-01T00:00:00.000Z"
}
) {
results {
id
name: attribute(key: "name")
outgoingEdges_SERVICE: outgoingEdges(neighborType: SERVICE) {
results {
neighbor {
name: attribute(key: "name")
}
}
}
outgoingEdges_BACKEND: outgoingEdges(neighborType: BACKEND) {
results {
neighbor {
name: attribute(key: "name")
}
}
}
incomingEdges_SERVICE: incomingEdges(neighborType: SERVICE) {
results {
neighbor {
name: attribute(key: "name")
}
}
}
}
}
}'
```