Skip to content

Configuration Reference

Jump to bottom
philipp-gatzka edited this page Dec 26, 2025 · 1 revision

Configuration Reference

Complete reference for all Graphite configuration options.

Spring Boot Configuration

All configuration properties use the graphite prefix in your application.yml or application.properties.

Basic Configuration

graphite:
  # Required: GraphQL endpoint URL
  url: https://api.example.com/graphql

  # Optional: Enable/disable the client (default: true)
  enabled: true

  # Optional: Client name for metrics tagging
  client-name: my-graphql-client

Headers

Static headers are added to every request:

graphite:
  headers:
    Authorization: Bearer ${GRAPHQL_TOKEN}
    X-API-Key: ${API_KEY}
    Accept-Language: en-US

For dynamic headers, see Advanced-Usage#Request-Interceptors.

Timeout Configuration

graphite:
  timeout:
    # Connection timeout - time to establish connection (default: 10s)
    connect: 10s

    # Read timeout - time waiting for response data (default: 30s)
    read: 30s

    # Overall request timeout - total time for entire request (default: 60s)
    request: 60s

Retry Configuration

Automatic retry for transient failures with exponential backoff:

graphite:
  retry:
    # Enable/disable retry (default: true)
    enabled: true

    # Maximum number of retry attempts (default: 3)
    max-attempts: 3

    # Initial delay between retries (default: 100ms)
    initial-delay: 100ms

    # Backoff multiplier - each retry waits multiplier * previous delay (default: 2.0)
    multiplier: 2.0

    # Maximum delay between retries (default: 5s)
    max-delay: 5s

Retries are triggered for:

  • Connection failures
  • HTTP 5xx responses
  • Request timeouts

Retries are not triggered for:

  • HTTP 4xx responses
  • GraphQL errors in the response body

Rate Limiting

Prevent overwhelming the GraphQL server:

graphite:
  rate-limit:
    # Enable/disable rate limiting (default: false)
    enabled: true

    # Maximum requests per second (default: 100)
    requests-per-second: 100

    # Burst capacity - allows temporary bursts above rps (default: same as rps)
    burst-capacity: 150

Connection Pool

Configure the HTTP connection pool:

graphite:
  connection-pool:
    # Maximum concurrent connections (default: 50)
    max-connections: 50

    # Idle connection timeout (default: 30s)
    idle-timeout: 30s

Metrics Configuration

Configure HTTP connection pool metrics:

graphite:
  metrics:
    http:
      # Enable/disable HTTP metrics (default: true)
      enabled: true

Code Generation Configuration

Gradle Plugin

graphite {
    // Required: Path to the introspection schema JSON file
    schemaFile = file("src/main/resources/graphql/schema.json")

    // Required: Base package for generated code
    packageName = "com.example.graphql"

    // Optional: Output directory (default: build/generated/sources/graphite/main/java)
    outputDir = layout.buildDirectory.dir("generated/sources/graphite/main/java")

    // Optional: Generate nullable annotations (default: true)
    generateNullableAnnotations = true

    // Optional: Custom scalar mappings
    scalars = mapOf(
        "DateTime" to "java.time.Instant",
        "Date" to "java.time.LocalDate",
        "BigDecimal" to "java.math.BigDecimal"
    )
}

Maven Plugin

<configuration>
    <!-- Required: Path to the introspection schema JSON file -->
    <schemaFile>${project.basedir}/src/main/resources/graphql/schema.json</schemaFile>

    <!-- Required: Base package for generated code -->
    <packageName>com.example.graphql</packageName>

    <!-- Optional: Output directory -->
    <outputDirectory>${project.build.directory}/generated-sources/graphite</outputDirectory>

    <!-- Optional: Generate nullable annotations -->
    <generateNullableAnnotations>true</generateNullableAnnotations>

    <!-- Optional: Custom scalar mappings -->
    <scalars>
        <DateTime>java.time.Instant</DateTime>
        <Date>java.time.LocalDate</Date>
        <BigDecimal>java.math.BigDecimal</BigDecimal>
    </scalars>
</configuration>

Programmatic Configuration

For advanced use cases, configure the client programmatically:

import io.github.graphite.GraphiteClient;
import io.github.graphite.GraphiteConfiguration;
import io.github.graphite.retry.RetryPolicy;
import io.github.graphite.ratelimit.RateLimitConfig;
import java.time.Duration;

GraphiteClient client = GraphiteClient.builder()
    .endpoint(URI.create("https://api.example.com/graphql"))
    .header("Authorization", "Bearer " + token)
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .requestTimeout(Duration.ofMinutes(1))
    .retryPolicy(RetryPolicy.builder()
        .maxAttempts(3)
        .initialDelay(Duration.ofMillis(100))
        .multiplier(2.0)
        .maxDelay(Duration.ofSeconds(5))
        .build())
    .rateLimitConfig(RateLimitConfig.of(100, 150))
    .build();

Environment Variables

All configuration properties can be overridden with environment variables:

# Format: GRAPHITE_<PROPERTY_PATH_WITH_UNDERSCORES>
GRAPHITE_URL=https://api.example.com/graphql
GRAPHITE_TIMEOUT_CONNECT=10s
GRAPHITE_RETRY_MAX_ATTEMPTS=5
GRAPHITE_HEADERS_AUTHORIZATION="Bearer ${TOKEN}"

Configuration Profiles

Use Spring profiles for environment-specific configuration:

# application.yml (common)
graphite:
  timeout:
    connect: 10s

---
# application-dev.yml
spring:
  config:
    activate:
      on-profile: dev
graphite:
  url: http://localhost:8080/graphql
  retry:
    enabled: false

---
# application-prod.yml
spring:
  config:
    activate:
      on-profile: prod
graphite:
  url: https://api.production.com/graphql
  retry:
    max-attempts: 5

Property Reference Table

Property Type Default Description
graphite.url String - GraphQL endpoint URL (required)
graphite.enabled boolean true Enable/disable the client
graphite.client-name String default Client name for metrics
graphite.headers.* Map {} Static request headers
graphite.timeout.connect Duration 10s Connection timeout
graphite.timeout.read Duration 30s Read timeout
graphite.timeout.request Duration 60s Overall request timeout
graphite.retry.enabled boolean true Enable retry
graphite.retry.max-attempts int 3 Max retry attempts
graphite.retry.initial-delay Duration 100ms Initial retry delay
graphite.retry.multiplier double 2.0 Backoff multiplier
graphite.retry.max-delay Duration 5s Maximum retry delay
graphite.rate-limit.enabled boolean false Enable rate limiting
graphite.rate-limit.requests-per-second double 100 Max requests/second
graphite.rate-limit.burst-capacity int 150 Burst capacity
graphite.connection-pool.max-connections int 50 Max connections
graphite.connection-pool.idle-timeout Duration 30s Idle timeout
graphite.metrics.http.enabled boolean true Enable HTTP metrics

See Also

Clone this wiki locally