Add AI meeting summaries

Author: benjie

notes/2025/summary-2025-07-24.md

@@ -0,0 +1,74 @@
+# Meeting Summary for OTel WG
+
+**NOTICE**: This summary was auto-generated by Zoom's "AI". AI-generated
+content may be inaccurate or misleading. Always check for accuracy. If in
+doubt, please consult the meeting recording at
+https://youtube.com/@GraphQLFoundation/playlists
+
+- Meeting start: 2025-07-24T17:00:36Z
+- Meeting end: 2025-07-24T18:14:55Z
+- Summary start: 2025-07-24T17:01:34Z
+- Summary end: 2025-07-24T18:12:29Z
+
+The meeting introduced participants to a work group focused on improving GraphQL observability, with discussions centered around tracing implementation, span naming conventions, and error handling in OpenTelemetry. The team explored various technical approaches including resolver tracking, path formatting, and error reporting mechanisms, while considering how to align with community practices and maintain compatibility across different telemetry tools. Pascal announced plans to prepare a draft specification for GraphQL telemetry and transition documentation to a semantic conventions repository, with the team agreeing to continue discussions through GitHub pull requests.
+
+## Next Steps
+
+- Team: Define span naming conventions for GraphQL resolver traces
+- Team: Determine how to handle resolver traces for public GraphQL APIs
+- Team: Consider different execution models when defining tracing specifications
+- Team: Specify how to trace root fields vs internal resolvers for performance monitoring
+- Team: Define attributes for distinguishing between mutation and query resolver traces
+- Team: Consider how to handle batching across different root fields in tracing specifications
+- Team: Discuss tracing specifications for GraphQL execution steps in future meetings
+- Team: Remove "is deprecated" attribute from the official specification
+- Team: Consider removing return type as an attribute
+- Team: Evaluate if "field.is deprecated" attribute should be extended to include information about deprecated arguments and types
+- Team: Review and potentially adjust the naming convention for resolver traces
+- Team: Consider how to handle asynchronous work in resolver traces
+- Pascal: Consult with Michael and Benjie about path formatting conventions in the GraphQL community
+- Pascal: Check if there are established practices for path formatting in GraphQL implementations
+- Pascal: Update the specification regarding path formatting options
+- Pascal: Evaluate if custom attributes like "lazy" or "asynchronous" should be included in the specification
+- Pascal: Create draft specification document from Excel content and make pull request to Semantic Conventions repository
+- Pascal: Prepare presentation for GraphQLConf work group about telemetry problems
+- Team: Continue discussions about error tracking and propagation in next meeting with Trask
+- Team: Review and provide feedback on pull request once it's made to Semantic Conventions repository
+
+## Summary
+
+### GraphQL Observability Work Group Introduction
+
+The meeting introduced participants to a work group focused on improving GraphQL observability, with Pascal hosting and explaining the purpose of their ongoing discussions. Attendees included Marco from Data Dog, Eli from PayPal, and Rob from Shopify, who shared their backgrounds and interests in GraphQL and observability. Pascal mentioned that the meeting would be published on YouTube and that they might use AI tools to generate meeting notes. The group discussed transitioning from a spreadsheet format to a draft specification format as they prepare for an upcoming conference, with Pascal emphasizing the need to move the project forward.
+
+### GraphQL Tracing Span Naming
+
+The team discussed GraphQL tracing implementation, focusing on span naming conventions and resolver tracing. Pascal explained that they will have a root GraphQL server operation trace with potential sub-traces for parsing, validation, variable coercion, and execution. The team debated how to name resolver spans, with Eli suggesting using descriptive names like "graphql.server.operation" or "server.resolver.field" while Marco raised questions about naming conventions and cardinality issues. They agreed to consult with Trask from the hotel funding team about resolver span naming conventions.
+
+### GraphQL API Security and Telemetry
+
+Eli and Pascal discussed the cardinality of span names in GraphQL server resolver traces, noting that while root traces are typically aggregated into time series, resolver traces have more flexibility. They explored how to mitigate potential vulnerabilities in HTTP URL paths and operation names, with Eli highlighting the importance of using matched paths from routers and discussing persistent queries as a defense mechanism. Pascal suggested that most GraphQL APIs should be private and use persistent operations, as this approach aligns with the needs of known clients and enhances the functionality of telemetry systems.
+
+### GraphQL Execution Tracking Strategies
+
+The group discussed different approaches to tracking entry points and execution in GraphQL systems, with Rob explaining their use of attribute-based data and root fields to manage resolver invocations and reduce instrumentation overhead. Pascal and Rob explored the differences between traditional GraphQL execution and GraphFast models, particularly around execution steps and federated architectures, while Marco raised questions about batching across root fields and the need for different levels of metrics (operation, root field, and resolver) for monitoring and dashboarding. The discussion concluded with Pascal suggesting that mutations deserve separate tracking from queries due to their sequential nature and transactional behavior, while queries can be treated more uniformly.
+
+### GraphQL Resolver Tracing Implementation
+
+The team discussed the implementation of resolver tracing in GraphQL, focusing on how to identify and attribute different resolver types and execution paths. Pascal explained the concept of coordinates for tracing, which can be used to uniquely identify resolvers across the schema. The group agreed that while all resolver executions could be traced, it's important to configure tracing levels based on system needs, with some implementations tracing everything while others focus on I/O operations. They also discussed the naming conventions for resolver traces, considering whether to include arguments and directives, and decided to propose "GraphQL Server Resolver Execution" as a potential name with explicit mention of whether arguments are included.
+
+### GraphQL Type Naming Conventions Discussion
+
+The team discussed terminology and naming conventions for GraphQL types and paths in OpenTelemetry. They debated whether to use "parent type" or "declaring type" and agreed that the return type could be removed as it's redundant with schema information. Rob suggested using a JSON array format for paths, which Pascal explained could be technically possible but might not be well-supported in all telemetry tools. The team also discussed the limitations of tracking deprecated fields and agreed that more schema-based information would be needed for comprehensive deprecation tracking.
+
+### Implementation Formatting and Specification Discussion
+
+The team discussed formatting options for implementations, with Pascal suggesting they should align with community practices and Marco advocating for a format with slashes for easier regex matching. They agreed to keep both path and alias information in the specification, with Pascal emphasizing their value for correlation and filtering. The group also considered adding attributes for lazy/async operations and error tracking, though they decided to defer further discussion on error handling to the next meeting.
+
+### GraphQL Error Tracking in Spans
+
+The team discussed how to handle errors in GraphQL spans for OpenTelemetry tracing. Pascal explained that spans are automatically marked as errors when resolvers fail to return a value, and there's no need to add additional failure markers. Eli emphasized the need to track errors across resolver operations, even when data is returned, to understand failure rates and error propagation. The team identified a challenge in tracking errors without null propagation, and agreed to further discuss how to annotate spans with error information in future meetings.
+
+### OpenTelemetry GraphQL Specification Planning
+
+The team discussed progress on resolver specifications and error reporting in OpenTelemetry. Pascal announced plans to prepare a draft specification for GraphQL telemetry and move existing documentation to the semantic conventions repository, where it will be available for implementation. The team agreed to continue discussions through GitHub pull requests rather than email threads, with Pascal committing to create and share a draft document within the next few weeks.