### VTEX IO Context Middleware Example - TypeScript

Source: https://github.com/vtex/node-vtex-api/blob/master/README.md

An example of a middleware function for VTEX IO services using TypeScript. It demonstrates accessing context, including state and IO clients, processing data, setting response status and headers, and calling the next middleware.

```typescript
export const example = async (ctx: Context, next: () => Promise<void>) => {
  const {state: {code}, clients: {apps}} = ctx
  console.log('Received code:', code)

  const apps = await apps.listApps()
  
  ctx.status = 200
  ctx.body = apps
  ctx.set('Cache-Control', 'private')

  await next()
}
```

--------------------------------

### Query Splunk Logs with Trace ID

Source: https://github.com/vtex/node-vtex-api/blob/master/docs/tracing.md

This example shows how to query Splunk logs for entries associated with a specific trace ID. It utilizes a Splunk query format to filter logs where the traceId field is not null.

```splunk
index=io_vtex_logs your-query-goes-here traceId!=NULL
```

--------------------------------

### Entrypoint Span

Source: https://github.com/vtex/node-vtex-api/blob/master/docs/tracing.md

Details on the entrypoint span created for each incoming request to the VTEX API.

```APIDOC
## Entrypoint Span

### Description
The native instrumentation creates an entrypoint span for each incoming request to the app. This span starts when the request is processed by Koa and finishes when the response streaming is complete.

### Method
Not Applicable (Automatic Instrumentation)

### Endpoint
Not Applicable (Automatic Instrumentation)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
Not Applicable

### Response
#### Success Response (200)
The entrypoint span includes tags related to the incoming request, such as:
- `span.kind`
- `http.url`
- `http.method`
- `http.path`
- `http.status_code`
- `vtex.request_id`
- `vtex.incoming.workspace`
- `vtex.incoming.account`

This span may also include error tags and logs if an error occurs. Incoming request headers and outgoing response headers are logged within this span.

#### Response Example
Not Applicable
```

--------------------------------

### Define VTEX IO Service with Route Handlers - JavaScript

Source: https://github.com/vtex/node-vtex-api/blob/master/README.md

Exports a new Service instance from '@vtex/api', defining route handlers and client options. It imports global types and specific handlers, setting up the service to handle requests through defined routes.

```javascript
import './globals'

import { Service } from '@vtex/api'

import { clients } from './clients'
import example from './handlers/example'

export default new Service({
  clients,
  routes: {
    example,
  },
})
```

--------------------------------

### Client HTTP(S) Calls

Source: https://github.com/vtex/node-vtex-api/blob/master/docs/tracing.md

Details on how VTEX API natively instruments client HTTP(S) requests for distributed tracing.

```APIDOC
## Client HTTP(S) calls

### Description
Every IOClient http(s) request is natively instrumented with tracing. The instrumentation creates a span wrapping the client's middlewares and a span for each HTTP request (including retries).

### Method
Not Applicable (Automatic Instrumentation)

### Endpoint
Not Applicable (Automatic Instrumentation)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
Not Applicable

### Response
#### Success Response (200)
For each client request, a `request` span wraps the client's middlewares, and an `http-request` child span wraps the actual HTTP request. If retries occur, multiple `http-request` spans might be generated.

A `request` span has the following tags:
- `http.cache.memoization.enabled`
- `http.cache.disk.enabled`
- `http.cache.memory.enabled`
- `http.client.name`
- `http.url`
- `http.method`

Additional cache-related tags might be present depending on the caching strategies:
- `http.cache.memory`
- `http.cache.memoization`
- `http.cache.disk`
- `http.cache.router`

On success, `http.status_code` is set.
If a request fails due to client errors (e.g., timeouts), `http.no_response` will be set to `true`.

The `http-request` span has the following tags:
- `span.kind`
- `http.method`
- `http.url`

It may also have:
- `http.status_code`
- `http.router_cache`

In case of a client error:
- `http.no_response`

Both `request` and `http-request` spans may have error tags and logs. Outgoing request headers and incoming response headers are logged in every `http-request` span. The span named `request` can have a suffix appended via configuration.

#### Response Example
Not Applicable
```

--------------------------------

### Process Tags

Source: https://github.com/vtex/node-vtex-api/blob/master/docs/tracing.md

Additional process tags generated by the native instrumentation in VTEX API.

```APIDOC
## Process Tags

### Description
These are additional process tags created by the native instrumentation within the VTEX API.

### Method
Not Applicable (Automatic Instrumentation)

### Endpoint
Not Applicable (Automatic Instrumentation)

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
Not Applicable

### Response
#### Success Response (200)
The additional process tags include:
- `app.linked`
- `app.node_vtex_api_version`
- `app.production`
- `app.region`
- `app.version`
- `app.workspace`
- `app.node_env`

All tags are documented in `Tags.ts`.

#### Response Example
Not Applicable
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.